ingitdb

README

Package ingitdb

inGitDB schema & config types.

Schema types

• type Definition — top-level schema definition; holds all collection definitions
  • type CollectionDef — schema for one collection
    • type RecordFileDef — describes the record file format and naming pattern
    • type ColumnDef — schema for a single field; see ColumnType
  • type ViewDef — materialized view definition (ordering, columns, format, top-N limit)

Configuration types

• package config
  • type RootConfig — parsed from .ingitdb.yaml; maps collection keys to paths

Documentation

Index

• Constants
• func Validate() func(*ReadOptions)
• func ValidateCollectionID(id string) error
• func ValidateColumnType(ct ColumnType) error
• type ChangeKind
• type ChangedFile
• type CollectionDef
  • func (v *CollectionDef) Validate() error
• type CollectionsReader
• type ColumnDef
  • func (v *ColumnDef) Validate() error
• type ColumnDefWithID
• type ColumnType
• type Definition
• type MaterializeResult
• type ProgressEvent
• type ProgressKind
• type ReadOption
• type ReadOptions
  • func NewReadOptions(o ...ReadOption) (opts ReadOptions)
  • func (o *ReadOptions) IsValidationRequired() bool
• type RecordEntry
• type RecordFileDef
  • func (rfd RecordFileDef) GetRecordFileName(record dal.Record) string
  • func (rfd RecordFileDef) Validate() error
• type RecordFormat
• type RecordType
• type RecordsReader
• type Scanner
• type Severity
• type ValidationError
  • func (v ValidationError) Error() string
• type ValidationResult
  • func (r *ValidationResult) Append(e ValidationError)
  • func (r *ValidationResult) ErrorCount() int
  • func (r *ValidationResult) Errors() []ValidationError
  • func (r *ValidationResult) Filter(fn func(ValidationError) bool) []ValidationError
  • func (r *ValidationResult) HasErrors() bool
• type ViewDef

Constants

const CollectionDefFileName = ".ingitdb-collection.yaml"

Functions

func Validate

func Validate() func(*ReadOptions)

func ValidateCollectionID

func ValidateCollectionID(id string) error

ValidateCollectionID validates a full collection ID. Allowed characters are alphanumeric and dot; ID must start/end with alphanumeric.

func ValidateColumnType

func ValidateColumnType(ct ColumnType) error

Types

type ChangeKind

type ChangeKind string

ChangeKind describes how a file changed between two git refs.

const (
	ChangeKindAdded    ChangeKind = "added"
	ChangeKindModified ChangeKind = "modified"
	ChangeKindDeleted  ChangeKind = "deleted"
	ChangeKindRenamed  ChangeKind = "renamed"
)

type ChangedFile

type ChangedFile struct {
	Kind    ChangeKind
	Path    string // repo-relative path
	OldPath string // set only for ChangeKindRenamed
}

ChangedFile is one file that differed between two git refs.

type CollectionDef

type CollectionDef struct {
	ID           string                `json:"-"`
	DirPath      string                `yaml:"-" json:"-"`
	Titles       map[string]string     `yaml:"titles,omitempty"`
	RecordFile   *RecordFileDef        `yaml:"record_file"`
	DataDir      string                `yaml:"data_dir,omitempty"`
	Columns      map[string]*ColumnDef `yaml:"columns"`
	ColumnsOrder []string              `yaml:"columns_order,omitempty"`
	DefaultView  string                `yaml:"default_view,omitempty"`
}

func (*CollectionDef) Validate

func (v *CollectionDef) Validate() error

type CollectionsReader

type CollectionsReader interface {
	ReadDefinition(dbPath string, opts ...ReadOption) (*Definition, error)
}

CollectionsReader loads the full database definition from disk. The default implementation wraps validator.ReadDefinition.

type ColumnDef

type ColumnDef struct {
	Type       ColumnType        `yaml:"type"`
	Title      string            `yaml:"title,omitempty"`
	Titles     map[string]string `yaml:"titles,omitempty"`
	ValueTitle string            `yaml:"valueTitle,omitempty"`
	Required   bool              `yaml:"required,omitempty"`
	Length     int               `yaml:"length,omitempty"`
	MinLength  int               `yaml:"min_length,omitempty"`
	MaxLength  int               `yaml:"max_length,omitempty"`
	ForeignKey string            `yaml:"foreign_key,omitempty"`
	// Locale pairs this column with a map[locale]string column named <this_column_name>+"s".
	// For example, column "title" with locale "en" is paired with column "titles".
	// When reading, the locale value is extracted from the pair column and exposed as this column.
	// When writing, this column is stored as-is in the file; if the pair column contains an entry
	// for the primary locale key, that entry is promoted here and removed from the pair column.
	Locale string `yaml:"locale,omitempty"`
}

func (*ColumnDef) Validate

func (v *ColumnDef) Validate() error

type ColumnDefWithID

type ColumnDefWithID struct {
	ID string `yaml:"id"`
	ColumnDef
}

type ColumnType

type ColumnType string

const (
	ColumnTypeL10N     ColumnType = "map[locale]string"
	ColumnTypeString   ColumnType = "string"
	ColumnTypeInt      ColumnType = "int"
	ColumnTypeFloat    ColumnType = "float"
	ColumnTypeBool     ColumnType = "bool"
	ColumnTypeDate     ColumnType = "date"
	ColumnTypeTime     ColumnType = "time"
	ColumnTypeDateTime ColumnType = "datetime"
	ColumnTypeAny      ColumnType = "any"
)

type Definition

type Definition struct {
	Collections map[string]*CollectionDef `yaml:"collections,omitempty"`
}

type MaterializeResult

type MaterializeResult struct {
	FilesWritten   int
	FilesUnchanged int
	Errors         []error
}

MaterializeResult summarises the outcome of a materialisation run.

type ProgressEvent

type ProgressEvent struct {
	Kind     ProgressKind
	TaskName string           // "validate" or "materialize"
	Scope    string           // collection or view ID
	ItemKey  string           // record key or output file name
	Done     int              // items completed so far
	Total    int              // total items; 0 = unknown
	Err      *ValidationError // non-nil only for ProgressKindError
}

ProgressEvent carries one progress update from a running task.

type ProgressKind

type ProgressKind string

ProgressKind describes the type of progress update.

const (
	ProgressKindStarted   ProgressKind = "started"
	ProgressKindItemDone  ProgressKind = "item_done"
	ProgressKindSkipped   ProgressKind = "skipped"
	ProgressKindCompleted ProgressKind = "completed"
	ProgressKindAborted   ProgressKind = "aborted"
	ProgressKindError     ProgressKind = "error"
)

type ReadOption

type ReadOption func(*ReadOptions)

type ReadOptions

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

func NewReadOptions

func NewReadOptions(o ...ReadOption) (opts ReadOptions)

func (*ReadOptions) IsValidationRequired

func (o *ReadOptions) IsValidationRequired() bool

type RecordEntry

type RecordEntry struct {
	Key      string // may be empty for list-type files
	FilePath string // absolute path
	Data     map[string]any
}

RecordEntry is one parsed record with its location on disk.

type RecordFileDef

type RecordFileDef struct {
	Name   string       `yaml:"name"`
	Format RecordFormat `yaml:"format"`

	// RecordType can have next values:
	// "map[string]any" - each record in a separate file
	// "[]map[string]any" - list of records
	// "map[string]map[string]any" - dictionary of records
	// "map[id]map[field]any" - all records in one file; top-level keys are record IDs, second level is field names
	RecordType RecordType `yaml:"type"`
}

func (RecordFileDef) GetRecordFileName

func (rfd RecordFileDef) GetRecordFileName(record dal.Record) string

func (RecordFileDef) Validate

func (rfd RecordFileDef) Validate() error

type RecordFormat

type RecordFormat string

type RecordType

type RecordType string

const (
	SingleRecord   RecordType = "map[string]any"
	ListOfRecords  RecordType = "[]map[string]any"
	MapOfRecords   RecordType = "map[string]map[string]any"
	MapOfIDRecords RecordType = "map[id]map[field]any"
)

type RecordsReader

type RecordsReader interface {
	ReadRecords(
		ctx context.Context,
		dbPath string,
		col *CollectionDef,
		yield func(RecordEntry) error,
	) error
}

RecordsReader streams records from one collection. Uses a yield callback to avoid goroutine leaks and keep allocation low.

type Scanner

type Scanner interface {
	// Scan walks dbPath, validates all records, and rebuilds all views.
	Scan(ctx context.Context, dbPath string, def *Definition) error
}

Scanner orchestrates the full pipeline: walk filesystem, invoke Validator and ViewBuilder.

type Severity

type Severity string

Severity is the level of a validation finding.

const (
	SeverityError   Severity = "error"
	SeverityWarning Severity = "warning"
)

type ValidationError

type ValidationError struct {
	Severity     Severity
	CollectionID string // e.g. "todo.tasks"
	FilePath     string // absolute path to offending file
	RecordKey    string // empty for list/map files where key is unknown
	FieldName    string // set for field-level errors
	Message      string
	Err          error // wrapped cause
}

ValidationError is one finding from data validation. All location fields (CollectionID…FieldName) are optional. Implements error.

func (ValidationError) Error

func (v ValidationError) Error() string

Error implements the error interface.

type ValidationResult

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

ValidationResult aggregates findings; mutex-protected for goroutine safety.

func (*ValidationResult) Append

func (r *ValidationResult) Append(e ValidationError)

Append adds a finding to the result.

func (*ValidationResult) ErrorCount

func (r *ValidationResult) ErrorCount() int

ErrorCount returns the total number of recorded findings.

func (*ValidationResult) Errors

func (r *ValidationResult) Errors() []ValidationError

Errors returns a snapshot copy of all findings.

func (*ValidationResult) Filter

func (r *ValidationResult) Filter(fn func(ValidationError) bool) []ValidationError

Filter returns findings that match the given predicate.

func (*ValidationResult) HasErrors

func (r *ValidationResult) HasErrors() bool

HasErrors reports whether any findings have been recorded.

type ViewDef

type ViewDef struct {
	ID      string            `yaml:"-"`
	Titles  map[string]string `yaml:"titles,omitempty"`
	OrderBy string            `yaml:"order_by,omitempty"`
	Formats []string          `yaml:"formats,omitempty"`
	Columns []string          `yaml:"columns,omitempty"`
	// How many records to include; 0 means all
	Top int `yaml:"top,omitempty"`
	// Template path relative to the collection directory.
	Template string `yaml:"template,omitempty"`
	// Output file name relative to the collection directory.
	FileName string `yaml:"file_name,omitempty"`
	// Template variable name for the records slice.
	RecordsVarName string `yaml:"records_var_name,omitempty"`
}