importer

type ExportMBTilesOptions struct {
	// TilesTable is the tinySQL table holding zoom_level/tile_column/tile_row/
	// tile_data. Defaults to "tiles".
	TilesTable string

	// MetadataTable holds name/value metadata rows. Defaults to
	// TilesTable + "_metadata", which is where ImportMBTiles puts it. A missing
	// table is not an error; Metadata below still applies.
	MetadataTable string

	// Metadata entries are written after the metadata table's rows, overriding
	// any key of the same name. Use it to supply or correct the keys the
	// specification requires.
	Metadata map[string]string

	// BatchSize bounds how many tiles are inserted per transaction. Zero uses a
	// default. Tiles are streamed, so a tileset larger than memory can be
	// written.
	BatchSize int

	// TileRowIsTMS declares what the source tile_row column already contains.
	// The specification stores TMS (row 0 = southernmost); if the tinySQL table
	// holds XYZ rows instead, set this false and the rows are flipped on the way
	// out. Defaults to true, matching a tileset that came from ImportMBTiles.
	TileRowIsTMS bool
}

type ExportMBTilesResult struct {
	TilesWritten    int64
	MetadataWritten int64
	// MinZoom and MaxZoom are the observed zoom range, also written to metadata
	// when the caller supplied neither. Both are -1 for an empty tileset.
	MinZoom int
	MaxZoom int
}

type FuzzyImportOptions struct {
	*ImportOptions

	// SkipInvalidRows skips rows that don't match the expected column count (default true)
	SkipInvalidRows bool

	// TrimWhitespace aggressively trims whitespace from all values (default true)
	TrimWhitespace bool

	// FixQuotes attempts to fix unmatched quotes in CSV data (default true)
	FixQuotes bool

	// CoerceTypes attempts to coerce invalid values to the expected type (default true)
	CoerceTypes bool

	// MaxSkippedRows maximum number of rows to skip before giving up (default 100)
	MaxSkippedRows int

	// AllowMixedTypes allows columns to have mixed types (converts to TEXT) (default true)
	AllowMixedTypes bool

	// FuzzyJSON attempts to parse malformed JSON (default true)
	FuzzyJSON bool

	// RemoveInvalidChars removes invalid UTF-8 characters (default true)
	RemoveInvalidChars bool

	// AutoFixDelimiters tries to detect and fix inconsistent delimiters (default true)
	AutoFixDelimiters bool
}

type ImportOptions struct {
	// MaxInputBytes rejects input that exceeds this size. Zero leaves the source
	// unbounded, which preserves the historic library behavior. Set this for
	// network and user-supplied input. For gzip CSV, the limit applies after
	// decompression.
	MaxInputBytes int64

	// MaxRecordBytes caps an individual NDJSON record. Zero uses the scanner's
	// standard limit. CSV records remain governed by encoding/csv.
	MaxRecordBytes int

	// Encoding selects the source text encoding. Empty or "auto" accepts a
	// UTF BOM when present and otherwise requires UTF-8. Legacy single-byte
	// encodings are opt-in: iso-8859-1, iso-8859-2, iso-8859-15, and
	// windows-1252. tinySQL always stores resulting TEXT as UTF-8.
	Encoding string

	// BatchSize controls how many rows are buffered before executing INSERT (default 1000).
	BatchSize int

	// NullLiterals are treated as SQL NULL (case-insensitive, trimmed).
	// Defaults: "", "null", "na", "n/a", "none", "#n/a"
	NullLiterals []string

	// CreateTable creates the table if it doesn't exist using inferred column types (default true).
	// Disable this if you want to create the table manually with specific types/constraints.
	CreateTable bool

	// Truncate clears the table before import (default false).
	Truncate bool

	// HeaderMode controls header detection:
	//   "auto" (default)  → heuristic decides based on data analysis
	//   "present"         → first row is always treated as header
	//   "absent"          → first row is data, synthetic column names generated (col_1, col_2, ...)
	HeaderMode string

	// DelimiterCandidates tested during auto-detection. Default: , ; \t |
	// Override to force specific delimiter(s).
	DelimiterCandidates []rune

	// TableName overrides the target table name (useful when importing from stdin/pipes).
	TableName string

	// SampleBytes caps the amount of data used for detection (default 128KB).
	SampleBytes int

	// SampleRecords caps the number of records analyzed for detection (default 500).
	SampleRecords int

	// TypeInference controls automatic type detection (default true).
	// When enabled, analyzes sample data to determine INT, FLOAT, BOOL, TIME, or TEXT.
	// When disabled, all columns default to TEXT type.
	TypeInference bool

	// DateTimeFormats lists custom datetime formats to try during type detection.
	// Defaults include RFC3339, ISO8601, common US/EU formats.
	DateTimeFormats []string

	// StrictTypes when true causes import to fail if data doesn't match detected types (default false).
	// When false, falls back to TEXT on type conversion errors.
	StrictTypes bool

	// TopoJSONObject selects a single top-level "objects" key when importing
	// a TopoJSON Topology (ImportTopoJSON). Empty imports every object; if
	// more than one object key exists in that case, each resulting row gets
	// an added "topo_object" property naming its source object, so a
	// multi-object Topology's provenance isn't silently lost. Ignored by
	// every other importer.
	TopoJSONObject string

	// XLSXSheet selects a single worksheet by name when importing an Excel
	// workbook (ImportXLSX). Empty selects the workbook's first sheet in
	// declared order. Ignored by every other importer.
	XLSXSheet string
}

type ImportResult struct {
	RowsInserted int64             // Total rows successfully inserted
	RowsSkipped  int64             // Rows skipped due to errors (if StrictTypes=false)
	Delimiter    rune              // Detected or configured delimiter
	HadHeader    bool              // Whether a header row was detected/configured
	Encoding     string            // Detected encoding: "utf-8", "utf-8-bom", "utf-16le", "utf-16be"
	LineEnding   string            // Detected line ending: "\n" or "\r\n"
	ColumnNames  []string          // Final column names used
	ColumnTypes  []storage.ColType // Detected column types
	Errors       []string          // Non-fatal errors encountered during import
}

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

type MBTilesArtifactManifest struct {
	FormatVersion  int                     `json:"format_version"`
	TinySQLVersion string                  `json:"tinysql_version"`
	Schema         MBTilesArtifactSchema   `json:"schema"`
	CreatedAt      time.Time               `json:"created_at"`
	Source         string                  `json:"source"`
	SourceBytes    int64                   `json:"source_bytes"`
	Resources      MBTilesResourceEstimate `json:"resources"`
	Provenance     map[string]any          `json:"provenance,omitempty"`
	Tables         []MBTilesArtifactTable  `json:"tables"`
	IndexConfig    map[string]any          `json:"index_config"`
	Checksums      map[string]string       `json:"checksums"`
}

type MBTilesArtifactOptions struct {
	Schema         MBTilesArtifactSchema
	BatchSize      int
	MaxMemoryBytes int64
	MinFreeBytes   int64
	// Provenance is optional caller-supplied, JSON-compatible source context.
	// tinySQL preserves it in the checksummed manifest but does not interpret
	// application-specific fields such as an OSM generator configuration.
	Provenance      map[string]any
	Progress        func(MBTilesProgress)
	ProgressEvery   time.Duration
	ReplaceExisting bool
}

type MBTilesArtifactResult struct {
	ArtifactPath string
	Manifest     MBTilesArtifactManifest
	Estimate     MBTilesResourceEstimate
}

type MBTilesArtifactSchema string

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

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

type MBTilesReader struct {
	// contains filtered or unexported fields
}

type MBTilesResourceEstimate 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 OpenMBTilesOptions struct {
	// TilesTable and MetadataTable name the tinySQL tables the tileset is
	// exposed as. They default to "tiles" and "tiles_metadata".
	TilesTable    string
	MetadataTable string

	// MaxTiles bounds how many tiles are admitted, guarding against
	// accidentally materializing a continental tileset. Zero means unlimited.
	MaxTiles int64

	// Zooms restricts the import to these zoom levels. Empty means all. This is
	// the practical way to work with a large tileset in place: overview zooms
	// are a tiny fraction of the tile count.
	Zooms []int

	// WithoutTileData omits tile_data, keeping only the addressing columns and
	// per-tile size/hash. A tile *index* of even a huge tileset is small, which
	// makes coverage and integrity queries cheap.
	WithoutTileData bool
}

type OpenMBTilesResult struct {
	TilesExposed    int64
	MetadataExposed int64
	MinZoom         int
	MaxZoom         int
	// Truncated is true when MaxTiles stopped the read before the source was
	// exhausted, so the exposed table is a partial view.
	Truncated bool
}

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

type TileArtifactSource interface {
	Info(context.Context) (TileArtifactInfo, error)
	ScanTiles(context.Context, func(TileArtifactTile) error) error
}

type TileArtifactTile struct {
	Z, X, Y int
	Data    []byte
}

type XMLRecord struct {
	XMLName xml.Name
	Attrs   []xml.Attr  `xml:",any,attr"`
	Content string      `xml:",chardata"`
	Nodes   []XMLRecord `xml:",any"`
}