internal

package
v0.0.20 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 21, 2025 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DecodeBase32ToUUID

func DecodeBase32ToUUID(s string) (uuid.UUID, error)

func DecodeFromBase32

func DecodeFromBase32(s string) ([]byte, error)

func EncodeToBase32

func EncodeToBase32(data []byte) string

func EncodeUUIDToBase32

func EncodeUUIDToBase32(id uuid.UUID) string

func FilterAttributes added in v0.0.18

func FilterAttributes(attributes map[string]any, attrs []string) map[string]any

FilterAttributes filters a map of attributes based on the requested attribute paths. If attrs is nil or empty, returns the original attributes unchanged. Supports nested paths like "contact.name" or "contact.phone".

func FilterDataRecord added in v0.0.18

func FilterDataRecord(record *forma.DataRecord, attrs []string) *forma.DataRecord

FilterDataRecord applies attribute filtering to a forma.DataRecord. Returns a new DataRecord with filtered attributes.

func MapKeys

func MapKeys[K comparable, V any](m map[K]V) []K

MapKeys extracts all keys from a map and returns them as a slice. The order of keys is non-deterministic due to map iteration.

func MapValues

func MapValues[K comparable, V any](m map[K]V) []V

MapValues extracts all values from a map and returns them as a slice. The order of values is non-deterministic due to map iteration.

func NewEntityManager

func NewEntityManager(
	transformer PersistentRecordTransformer,
	repository PersistentRecordRepository,
	registry forma.SchemaRegistry,
	config *forma.Config,
) forma.EntityManager

NewEntityManager creates a new EntityManager instance

func NewFileSchemaRegistry

func NewFileSchemaRegistry(pool *pgxpool.Pool, schemaTable string, schemaDir string) (forma.SchemaRegistry, error)

NewFileSchemaRegistry creates a new schema registry that reads schema mappings from a PostgreSQL table and loads attribute definitions from JSON files.

Parameters:

  • pool: PostgreSQL connection pool
  • schemaTable: Name of the schema_registry table (e.g., "schema_registry_1234567890")
  • schemaDir: Directory containing the *_attributes.json files

func NewFileSchemaRegistryFromDirectory added in v0.0.15

func NewFileSchemaRegistryFromDirectory(schemaDir string) (forma.SchemaRegistry, error)

NewFileSchemaRegistryFromDirectory creates a schema registry that scans a directory for schema files and auto-assigns IDs (starting from 100). This mode does not require a database connection.

Parameters:

  • schemaDir: Directory containing the schema files (*.json and *_attributes.json)

func ToFloat64 added in v0.0.19

func ToFloat64(v any) (float64, bool)

ToFloat64Ok is an exported helper that behaves like the legacy optimizer helper: it returns (float64, bool) where bool indicates success.

Types

type AttributeConverter

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

AttributeConverter provides conversion between EntityAttribute and EAVRecord

func NewAttributeConverter

func NewAttributeConverter(registry forma.SchemaRegistry) *AttributeConverter

NewAttributeConverter creates a new AttributeConverter instance

func (*AttributeConverter) FromEAVRecord

func (c *AttributeConverter) FromEAVRecord(record EAVRecord, valueType forma.ValueType) (EntityAttribute, error)

FromEAVRecord converts an EAVRecord to an EntityAttribute

func (*AttributeConverter) FromEAVRecords

func (c *AttributeConverter) FromEAVRecords(records []EAVRecord) ([]EntityAttribute, error)

FromEAVRecords converts a slice of EAVRecords to EntityAttributes

func (*AttributeConverter) ToEAVRecord

func (c *AttributeConverter) ToEAVRecord(attr EntityAttribute, rowID uuid.UUID) (EAVRecord, error)

ToEAVRecord converts an EntityAttribute to an EAVRecord

func (*AttributeConverter) ToEAVRecords

func (c *AttributeConverter) ToEAVRecords(attributes []EntityAttribute, rowID uuid.UUID) ([]EAVRecord, error)

ToEAVRecords converts a slice of EntityAttributes to EAVRecords

type AttributeOrder

type AttributeOrder struct {
	AttrID          int16
	ValueType       forma.ValueType
	SortOrder       forma.SortOrder
	StorageLocation forma.AttributeStorageLocation // main or eav
	ColumnName      string                         // main table column name if StorageLocation == main
}

AttributeOrder specifies how to sort by a particular attribute.

func (*AttributeOrder) AttrIDInt

func (ao *AttributeOrder) AttrIDInt() int

AttrIDInt returns the attribute ID as an int (for template compatibility).

func (*AttributeOrder) Desc

func (ao *AttributeOrder) Desc() bool

Desc returns true if the sort order is descending.

func (*AttributeOrder) IsMainColumn

func (ao *AttributeOrder) IsMainColumn() bool

IsMainColumn returns true if the attribute is stored in the main table.

func (*AttributeOrder) MainColumnName

func (ao *AttributeOrder) MainColumnName() string

MainColumnName returns the column name in the main table.

func (*AttributeOrder) ValueColumn

func (ao *AttributeOrder) ValueColumn() string

ValueColumn returns the EAV table column name for this attribute's value type.

type AttributeQuery

type AttributeQuery struct {
	SchemaID        int16            `json:"schemaId"`
	Condition       forma.Condition  `json:"condition,omitempty"`
	OrderBy         []forma.OrderBy  `json:"orderBy"`
	AttributeOrders []AttributeOrder `json:"attributeOrders"`
	Limit           int              `json:"limit"`
	Offset          int              `json:"offset"`
}

type DBPool added in v0.0.19

type DBPool interface {
	Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
}

DBPool is a minimal interface for the methods MetadataLoader needs.

type EAVRecord

type EAVRecord struct {
	SchemaID     int16
	RowID        uuid.UUID // UUID v7, identifies data row
	AttrID       int16     // Attribute ID from schema definition
	ArrayIndices string    // Comma-separated array indices (e.g., "0", "1,2", or "" for non-arrays)
	ValueText    *string   // For valueType: "text"
	ValueNumeric *float64  // For valueType: "numeric"
}

ValueType represents the type of value stored in a row of EAV table.

type EntityAttribute

type EntityAttribute struct {
	SchemaID     int16
	RowID        uuid.UUID // UUID v7, identifies data row
	AttrID       int16
	ArrayIndices string
	ValueType    forma.ValueType
	Value        any
}

func (*EntityAttribute) BigInt

func (ea *EntityAttribute) BigInt() (*int64, error)

func (*EntityAttribute) Bool

func (ea *EntityAttribute) Bool() (*bool, error)

func (*EntityAttribute) Date

func (ea *EntityAttribute) Date() (*time.Time, error)

func (*EntityAttribute) DateTime

func (ea *EntityAttribute) DateTime() (*time.Time, error)

func (*EntityAttribute) Integer

func (ea *EntityAttribute) Integer() (*int32, error)

func (*EntityAttribute) Numeric

func (ea *EntityAttribute) Numeric() (*float64, error)

func (*EntityAttribute) SmallInt

func (ea *EntityAttribute) SmallInt() (*int16, error)

func (*EntityAttribute) Text

func (ea *EntityAttribute) Text() (*string, error)

func (*EntityAttribute) UUID

func (ea *EntityAttribute) UUID() (*uuid.UUID, error)

type MetadataCache

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

MetadataCache holds all metadata mappings for fast lookups

func NewMetadataCache

func NewMetadataCache() *MetadataCache

NewMetadataCache creates a new metadata cache

func (*MetadataCache) GetSchemaCache

func (mc *MetadataCache) GetSchemaCache(schemaName string) (forma.SchemaAttributeCache, bool)

GetSchemaCache retrieves the schema attribute cache for a schema (thread-safe)

func (*MetadataCache) GetSchemaCacheByID added in v0.0.10

func (mc *MetadataCache) GetSchemaCacheByID(schemaID int16) (forma.SchemaAttributeCache, bool)

func (*MetadataCache) GetSchemaID

func (mc *MetadataCache) GetSchemaID(schemaName string) (int16, bool)

GetSchemaID retrieves schema ID by name (thread-safe)

func (*MetadataCache) GetSchemaName

func (mc *MetadataCache) GetSchemaName(schemaID int16) (string, bool)

GetSchemaName retrieves schema name by ID (thread-safe)

func (*MetadataCache) ListSchemas

func (mc *MetadataCache) ListSchemas() []string

ListSchemas returns all schema names (thread-safe)

type MetadataLoader

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

MetadataLoader loads schema and attribute metadata from database and JSON files

func NewMetadataLoader

func NewMetadataLoader(pool DBPool, schemaTableName, schemaDirectory string) *MetadataLoader

NewMetadataLoader creates a new metadata loader

func (*MetadataLoader) LoadMetadata

func (ml *MetadataLoader) LoadMetadata(ctx context.Context) (*MetadataCache, error)

LoadMetadata loads all metadata and returns a cache

type PersistentRecord

type PersistentRecord struct {
	SchemaID        int16
	RowID           uuid.UUID
	TextItems       map[string]string // e.g., "text_01" -> "Hello"
	Int16Items      map[string]int16
	Int32Items      map[string]int32
	Int64Items      map[string]int64
	Float64Items    map[string]float64
	UUIDItems       map[string]uuid.UUID
	CreatedAt       int64
	UpdatedAt       int64
	DeletedAt       *int64
	OtherAttributes []EAVRecord // EAV attributes not in hot table
}

* PersistentRecord 是一个用于表示持久化存储记录的结构体,包含了`entity main`和EAV Attributes。

type PersistentRecordPage

type PersistentRecordPage struct {
	Records      []*PersistentRecord
	TotalRecords int64
	TotalPages   int
	CurrentPage  int
}

type PersistentRecordQuery

type PersistentRecordQuery struct {
	Tables          StorageTables
	SchemaID        int16
	Condition       forma.Condition
	AttributeOrders []AttributeOrder
	Limit           int
	Offset          int
}

type PersistentRecordRepository

type PersistentRecordRepository interface {
	InsertPersistentRecord(ctx context.Context, tables StorageTables, record *PersistentRecord) error
	UpdatePersistentRecord(ctx context.Context, tables StorageTables, record *PersistentRecord) error
	DeletePersistentRecord(ctx context.Context, tables StorageTables, schemaID int16, rowID uuid.UUID) error
	GetPersistentRecord(ctx context.Context, tables StorageTables, schemaID int16, rowID uuid.UUID) (*PersistentRecord, error)
	QueryPersistentRecords(ctx context.Context, query *PersistentRecordQuery) (*PersistentRecordPage, error)
}

type PersistentRecordTransformer

type PersistentRecordTransformer interface {
	ToPersistentRecord(ctx context.Context, schemaID int16, rowID uuid.UUID, jsonData any) (*PersistentRecord, error)
	FromPersistentRecord(ctx context.Context, record *PersistentRecord) (map[string]any, error)
}

func NewPersistentRecordTransformer

func NewPersistentRecordTransformer(registry forma.SchemaRegistry) PersistentRecordTransformer

NewPersistentRecordTransformer creates a new PersistentRecordTransformer instance

type PostgresPersistentRecordRepository

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

func NewPostgresPersistentRecordRepository

func NewPostgresPersistentRecordRepository(pool *pgxpool.Pool, metadataCache *MetadataCache) *PostgresPersistentRecordRepository

func (*PostgresPersistentRecordRepository) DeletePersistentRecord

func (r *PostgresPersistentRecordRepository) DeletePersistentRecord(ctx context.Context, tables StorageTables, schemaID int16, rowID uuid.UUID) error

func (*PostgresPersistentRecordRepository) GetPersistentRecord

func (r *PostgresPersistentRecordRepository) GetPersistentRecord(ctx context.Context, tables StorageTables, schemaID int16, rowID uuid.UUID) (*PersistentRecord, error)

func (*PostgresPersistentRecordRepository) InsertPersistentRecord

func (r *PostgresPersistentRecordRepository) InsertPersistentRecord(ctx context.Context, tables StorageTables, record *PersistentRecord) error

func (*PostgresPersistentRecordRepository) QueryPersistentRecords

func (*PostgresPersistentRecordRepository) UpdatePersistentRecord

func (r *PostgresPersistentRecordRepository) UpdatePersistentRecord(ctx context.Context, tables StorageTables, record *PersistentRecord) error

type RelationDescriptor added in v0.0.18

type RelationDescriptor struct {
	ChildSchema        string
	ChildPath          string
	ParentSchema       string
	ParentPath         string
	ForeignKeyAttr     string
	ParentIDAttr       string
	ForeignKeyRequired bool
}

RelationDescriptor captures how a child schema derives fields from a parent schema.

type RelationIndex added in v0.0.18

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

RelationIndex stores parent-child relations keyed by child schema name.

func LoadRelationIndex added in v0.0.18

func LoadRelationIndex(schemaDir string) (*RelationIndex, error)

LoadRelationIndex parses JSON schema files in schemaDir and builds a relation index. If the directory is missing or no relations are found, it returns an empty index.

func (*RelationIndex) Relations added in v0.0.18

func (idx *RelationIndex) Relations(schema string) []RelationDescriptor

Relations returns descriptors for a child schema.

func (*RelationIndex) StripComputedFields added in v0.0.18

func (idx *RelationIndex) StripComputedFields(schema string, data map[string]any) map[string]any

StripComputedFields removes relation-backed attributes from the payload before persistence.

type SQLGenerator

type SQLGenerator struct{}

SQLGenerator converts parsed conditions into SQL fragments and argument lists.

func NewSQLGenerator

func NewSQLGenerator() *SQLGenerator

NewSQLGenerator constructs a SQLGenerator.

func (*SQLGenerator) ToSqlClauses

func (g *SQLGenerator) ToSqlClauses(
	condition forma.Condition,
	eavTable string,
	schemaID int16,
	cache forma.SchemaAttributeCache,
	paramIndex *int,
) (string, []any, error)

ToSqlClauses builds the SQL clause and arguments for a condition tree.

type SchemaMetadata

type SchemaMetadata struct {
	SchemaName    string                    `json:"schema_name"`
	SchemaID      int16                     `json:"schema_id"`
	SchemaVersion int                       `json:"schema_version"`
	Attributes    []forma.AttributeMetadata `json:"attributes"`
}

SchemaMetadata aggregates attribute mappings for a schema version.

type Set

type Set[T comparable] struct {
	// contains filtered or unexported fields
}

Set is a generic data structure that represents a collection of unique items. It uses a map internally for O(1) operations.

func NewSet

func NewSet[T comparable]() *Set[T]

NewSet creates and returns a new empty Set.

func (*Set[T]) Add

func (s *Set[T]) Add(item T)

Add inserts an item into the set. If the item already exists, it has no effect.

func (*Set[T]) Clear

func (s *Set[T]) Clear()

Clear removes all items from the set.

func (*Set[T]) Contains

func (s *Set[T]) Contains(item T) bool

Contains checks if an item exists in the set.

func (*Set[T]) Remove

func (s *Set[T]) Remove(item T)

Remove deletes an item from the set. If the item doesn't exist, it has no effect.

func (*Set[T]) Size

func (s *Set[T]) Size() int

Size returns the number of items in the set.

func (*Set[T]) ToSlice

func (s *Set[T]) ToSlice() []T

ToSlice converts the set to a slice containing all items. The order of items is non-deterministic due to map iteration.

type StorageTables

type StorageTables struct {
	EntityMain string
	EAVData    string
}

type Transformer

type Transformer interface {
	// Single object conversion
	ToAttributes(ctx context.Context, schemaID int16, rowID uuid.UUID, jsonData any) ([]EntityAttribute, error)
	FromAttributes(ctx context.Context, attributes []EntityAttribute) (map[string]any, error)

	// Batch operations
	BatchToAttributes(ctx context.Context, schemaID int16, jsonObjects []any) ([]EntityAttribute, error)
	BatchFromAttributes(ctx context.Context, attributes []EntityAttribute) ([]map[string]any, error)

	// Validation
	ValidateAgainstSchema(ctx context.Context, jsonSchema any, jsonData any) error
}

func NewTransformer

func NewTransformer(registry forma.SchemaRegistry) Transformer

NewTransformer creates a new Transformer instance backed by the provided schema registry.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL