Documentation
¶
Index ¶
- func DecodeBase32ToUUID(s string) (uuid.UUID, error)
- func DecodeFromBase32(s string) ([]byte, error)
- func EncodeToBase32(data []byte) string
- func EncodeUUIDToBase32(id uuid.UUID) string
- func FilterAttributes(attributes map[string]any, attrs []string) map[string]any
- func FilterDataRecord(record *forma.DataRecord, attrs []string) *forma.DataRecord
- func MapKeys[K comparable, V any](m map[K]V) []K
- func MapValues[K comparable, V any](m map[K]V) []V
- func NewEntityManager(transformer PersistentRecordTransformer, repository PersistentRecordRepository, ...) forma.EntityManager
- func NewFileSchemaRegistry(pool *pgxpool.Pool, schemaTable string, schemaDir string) (forma.SchemaRegistry, error)
- func NewFileSchemaRegistryFromDirectory(schemaDir string) (forma.SchemaRegistry, error)
- func ToFloat64(v any) (float64, bool)
- type AttributeConverter
- func (c *AttributeConverter) FromEAVRecord(record EAVRecord, valueType forma.ValueType) (EntityAttribute, error)
- func (c *AttributeConverter) FromEAVRecords(records []EAVRecord) ([]EntityAttribute, error)
- func (c *AttributeConverter) ToEAVRecord(attr EntityAttribute, rowID uuid.UUID) (EAVRecord, error)
- func (c *AttributeConverter) ToEAVRecords(attributes []EntityAttribute, rowID uuid.UUID) ([]EAVRecord, error)
- type AttributeOrder
- type AttributeQuery
- type DBPool
- type EAVRecord
- type EntityAttribute
- func (ea *EntityAttribute) BigInt() (*int64, error)
- func (ea *EntityAttribute) Bool() (*bool, error)
- func (ea *EntityAttribute) Date() (*time.Time, error)
- func (ea *EntityAttribute) DateTime() (*time.Time, error)
- func (ea *EntityAttribute) Integer() (*int32, error)
- func (ea *EntityAttribute) Numeric() (*float64, error)
- func (ea *EntityAttribute) SmallInt() (*int16, error)
- func (ea *EntityAttribute) Text() (*string, error)
- func (ea *EntityAttribute) UUID() (*uuid.UUID, error)
- type MetadataCache
- func (mc *MetadataCache) GetSchemaCache(schemaName string) (forma.SchemaAttributeCache, bool)
- func (mc *MetadataCache) GetSchemaCacheByID(schemaID int16) (forma.SchemaAttributeCache, bool)
- func (mc *MetadataCache) GetSchemaID(schemaName string) (int16, bool)
- func (mc *MetadataCache) GetSchemaName(schemaID int16) (string, bool)
- func (mc *MetadataCache) ListSchemas() []string
- type MetadataLoader
- type PersistentRecord
- type PersistentRecordPage
- type PersistentRecordQuery
- type PersistentRecordRepository
- type PersistentRecordTransformer
- type PostgresPersistentRecordRepository
- func (r *PostgresPersistentRecordRepository) DeletePersistentRecord(ctx context.Context, tables StorageTables, schemaID int16, rowID uuid.UUID) error
- func (r *PostgresPersistentRecordRepository) GetPersistentRecord(ctx context.Context, tables StorageTables, schemaID int16, rowID uuid.UUID) (*PersistentRecord, error)
- func (r *PostgresPersistentRecordRepository) InsertPersistentRecord(ctx context.Context, tables StorageTables, record *PersistentRecord) error
- func (r *PostgresPersistentRecordRepository) QueryPersistentRecords(ctx context.Context, query *PersistentRecordQuery) (*PersistentRecordPage, error)
- func (r *PostgresPersistentRecordRepository) UpdatePersistentRecord(ctx context.Context, tables StorageTables, record *PersistentRecord) error
- type RelationDescriptor
- type RelationIndex
- type SQLGenerator
- type SchemaMetadata
- type Set
- type StorageTables
- type Transformer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecodeFromBase32 ¶
func EncodeToBase32 ¶
func EncodeUUIDToBase32 ¶
func FilterAttributes ¶ added in v0.0.18
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)
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 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) 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)
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 (r *PostgresPersistentRecordRepository) QueryPersistentRecords(ctx context.Context, query *PersistentRecordQuery) (*PersistentRecordPage, error)
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
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 (*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.
type StorageTables ¶
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.
Source Files
¶
- advanced_query_template.go
- attribute_converter.go
- attribute_filter.go
- base32.go
- collections.go
- entity_manager.go
- entity_manager_batch.go
- entity_manager_crud.go
- entity_manager_helpers.go
- entity_manager_query.go
- entity_manager_relations.go
- file_schema_registry.go
- interfaces.go
- metadata_loader.go
- metadata_parser.go
- metadata_types.go
- persistent_transformer.go
- postgres_persistent_repository.go
- relation_index.go
- schema_metadata_cache.go
- sql_generator.go
- sql_helpers.go
- transformer.go
- types.go
- utils.go