entity

package
v1.2.170 Latest Latest
Warning

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

 Go to latest Published: Nov 25, 2025 License: MIT Imports: 10 Imported by: 19

Documentation

Overview

Package entity Entity interface and base entity for all persistent model entities

Index

Constants

This section is empty.

Variables

View Source 
var TimePeriodCodes = &timePeriodCode{
	UNDEFINED: 0,
	MINUTE:    1,
	HOUR:      2,
	DAY:       3,
	WEEK:      4,
	MONTH:     5,
}

TimePeriodCodes is a singleton instance containing all available time period codes.

Functions

func ConvertISO8601Format added in v1.2.122 

func ConvertISO8601Format(format string) string

ConvertISO8601Format converts a custom date format string (e.g., "YYYY-MM-DD") to Go's reference time format. This helper function allows using more familiar format strings instead of Go's specific reference date (Mon Jan 2 15:04:05 MST 2006).

func EntityIndex 

func EntityIndex(entity Entity, tenantId string) string

EntityIndex extracts the table or index name from entity.TABLE() and applies template replacements. It replaces placeholders like {{tenantId}}, {{accountId}}, {{year}}, and {{month}} with actual values. This is useful for dynamic table naming strategies, such as time-based or tenant-based sharding.

Parameters:

  • entity: The entity instance to derive the index from.
  • tenantId: The tenant ID to replace {{tenantId}} or {{accountId}} placeholders.

Returns:

  • The resolved index or table name.

func GUID added in v1.1.2 

func GUID() string

GUID generates a new Global Unique Identifier (UUID v4). It uses the github.com/google/uuid library.

func ID added in v1.1.2 

func ID() string

ID returns a long string (alphanumeric) based on Epoch micro-seconds in base 36. It generates a unique identifier that is time-ordered and relatively compact.

func IDN added in v1.2.21 

func IDN() string

IDN returns a long string (digits only) based on Epoch micro-seconds. It is similar to ID() but uses only numeric characters.

func JsonUnmarshal added in v1.2.105 

func JsonUnmarshal(data Json, v any) error

JsonUnmarshal converts a generic Json map (map[string]any) to a specific Go value. It first marshals the map to JSON bytes, then unmarshals it into the target value.

func Marshal added in v1.2.55 

func Marshal(v any) ([]byte, error)

Marshal returns the JSON encoding of v. It is a wrapper around json.Marshal.

func NanoID added in v1.1.2 

func NanoID() string

NanoID returns a long string (21 characters) based on the go-nanoid project. It is smaller and faster than UUID, and URL-friendly. If generation fails, it falls back to a time-based ID.

func ShortID added in v1.1.2 

func ShortID(delta ...int) string

ShortID returns a short string (6 characters alphanumeric) based on epoch seconds in base 36. It accepts optional delta values to offset the timestamp, which can be useful for generating IDs in the past or future, or adding entropy.

func ShortIDN added in v1.2.21 

func ShortIDN(delta ...int) string

ShortIDN returns a short string (digits only) based on epoch seconds. It accepts optional delta values similar to ShortID.

func Unmarshal added in v1.2.55 

func Unmarshal(data []byte, v any) error

Unmarshal parses the JSON-encoded data and stores the result in the value pointed to by v. It is a wrapper around json.Unmarshal.

Types

type BaseAnalyticEntity added in v1.2.140 

type BaseAnalyticEntity struct {
}

BaseAnalyticEntity is a base structure for analytical entities. Unlike BaseEntity, it does not enforce a standard ID or timestamp fields, making it suitable for data points, logs, or other analytical data that might have different identification or timing requirements.

func (*BaseAnalyticEntity) ID added in v1.2.140 

func (e *BaseAnalyticEntity) ID() string

func (*BaseAnalyticEntity) KEY added in v1.2.140 

func (e *BaseAnalyticEntity) KEY() string

func (*BaseAnalyticEntity) NAME added in v1.2.140 

func (e *BaseAnalyticEntity) NAME() string

func (*BaseAnalyticEntity) TABLE added in v1.2.140 

func (e *BaseAnalyticEntity) TABLE() string

type BaseEntity 

type BaseEntity struct {
	Id        string    `json:"id"`        // Id is the unique object identifier
	CreatedOn Timestamp `json:"createdOn"` // CreatedOn is the timestamp when the object was created [Epoch milliseconds Timestamp]
	UpdatedOn Timestamp `json:"updatedOn"` // UpdatedOn is the timestamp when the object was last updated [Epoch milliseconds Timestamp]
}

BaseEntity is a base structure for any concrete Entity. It provides common fields like Id, CreatedOn, and UpdatedOn that are standard across most entities. Embed this struct in your domain entities to inherit these standard fields and basic behavior.

func (*BaseEntity) ID 

func (e *BaseEntity) ID() string

func (*BaseEntity) KEY 

func (e *BaseEntity) KEY() string

func (*BaseEntity) NAME 

func (e *BaseEntity) NAME() string

func (*BaseEntity) TABLE 

func (e *BaseEntity) TABLE() string

type BaseEntityEx added in v1.2.116 

type BaseEntityEx struct {
	Id        string    `json:"id"`        // Id is the unique object identifier
	CreatedOn Timestamp `json:"createdOn"` // CreatedOn is the timestamp when the object was created [Epoch milliseconds Timestamp]
	UpdatedOn Timestamp `json:"updatedOn"` // UpdatedOn is the timestamp when the object was last updated [Epoch milliseconds Timestamp]
	Flag      int64     `json:"flag"`      // Flag represents the entity status (e.g. -1 = deleted, 0 = active)
	Props     Json      `json:"props"`     // Props is a map of custom properties for extensibility
}

BaseEntityEx is an extended base Entity with custom attributes. It includes all fields from BaseEntity and adds support for a status Flag and a generic properties map (Props). This is useful for entities that need soft-delete capabilities (via Flag) or extensible fields (via Props).

func (*BaseEntityEx) ID added in v1.2.116 

func (e *BaseEntityEx) ID() string

func (*BaseEntityEx) KEY added in v1.2.116 

func (e *BaseEntityEx) KEY() string

func (*BaseEntityEx) NAME added in v1.2.116 

func (e *BaseEntityEx) NAME() string

func (*BaseEntityEx) TABLE added in v1.2.116 

func (e *BaseEntityEx) TABLE() string

type Entities added in v1.2.104 

type Entities[T any] struct {
	Values []T `json:"values"` // Values is the list of wrapped entities or values
}

Entities is a generic wrapper to express a list of primitive or complex types as an Entity. It allows a collection of items to be treated as a single Entity unit.

func (*Entities[T]) Add added in v1.2.104 

func (e *Entities[T]) Add(item T) int

Add appends an item to the Entities list and returns the new count.

func (*Entities[T]) ID added in v1.2.104 

func (e *Entities[T]) ID() string

func (*Entities[T]) KEY added in v1.2.104 

func (e *Entities[T]) KEY() string

func (*Entities[T]) NAME added in v1.2.104 

func (e *Entities[T]) NAME() string

func (*Entities[T]) TABLE added in v1.2.104 

func (e *Entities[T]) TABLE() string

type Entity 

type Entity interface {
	// ID returns the entity unique Id.
	// This ID is used to uniquely identify the entity within its table or collection.
	ID() string

	// TABLE returns the entity table name.
	// For sharded entities, the table name may include the suffix of the tenant id.
	// This is used by the storage layer to determine where to persist the entity.
	TABLE() string

	// NAME returns the entity name.
	// This is typically used for logging, display, or logical identification of the entity type.
	NAME() string

	// KEY returns the entity sharding key (tenant/account id) based on one of the entity's attributes.
	// This key is crucial for distributed systems where data is partitioned by tenant or account.
	KEY() string
}

Entity is a marker interface for all serialized domain model entities with identity. Any struct that needs to be persisted or manipulated as a domain entity must implement this interface.

func CloneEntity added in v1.2.159 

func CloneEntity(ef EntityFactory, src Entity) (Entity, error)

CloneEntity performs a deep clone of an entity using JSON serialization. It creates a new instance using the provided EntityFactory and copies the data from the source entity.

Parameters:

  • ef: The EntityFactory to create the destination entity.
  • src: The source entity to clone.

Returns:

  • A new Entity instance with the same data as src, or an error if cloning fails.

func NewBaseEntity added in v1.2.41 

func NewBaseEntity() Entity

NewBaseEntity creates a new BaseEntity instance with the current time for CreatedOn and UpdatedOn. This is a helper function to initialize a BaseEntity with valid timestamps.

func NewBaseEntityEx added in v1.2.116 

func NewBaseEntityEx() Entity

NewBaseEntityEx creates a new BaseEntityEx instance with initialized timestamps and an empty Props map.

func NewEntities added in v1.2.104 

func NewEntities[T any]() Entity

NewEntities creates a new Entities instance with an empty list.

func NewSimpleEntity added in v1.2.41 

func NewSimpleEntity[T any]() Entity

NewSimpleEntity creates a new SimpleEntity instance.

type EntityAction 

type EntityAction int

EntityAction represents the type of action performed on an entity. 

const (
	// AddEntity represents an action to add a new entity.
	AddEntity EntityAction = 1
	// UpdateEntity represents an action to update an existing entity.
	UpdateEntity EntityAction = 2
	// DeleteEntity represents an action to delete an entity.
	DeleteEntity EntityAction = 3
)

type EntityFactory 

type EntityFactory func() Entity

EntityFactory is the factory method signature for creating new Entity instances. It is used by the framework to instantiate entities dynamically, for example when unmarshalling from a database.

type Error added in v1.2.153 

type Error interface {
	Error() string
	Code() int
}

Error interface defines the contract for error handling in the application. It extends the standard error interface with a numeric code, allowing for more structured error handling.

func NewError added in v1.2.154 

func NewError(code int, text string) Error

NewError creates a new Error instance with the specified code and text.

type Json 

type Json map[string]any

Json Represent arbitrary JSON fields collection It is a map of string to any, used for flexible data structures.

func JsonMarshal added in v1.2.105 

func JsonMarshal(v any) (Json, error)

JsonMarshal converts any Go value to a generic Json map (map[string]any). It first marshals the value to JSON bytes, then unmarshals it back into a map. This is useful for converting structs to maps.

type JsonDoc 

type JsonDoc struct {
	Id   string // Id is the unique identifier of the document
	Data string // Data is the raw JSON string content
}

JsonDoc is a Json document to store in Document object store (Postgres, ElasticSearch, Couchbase ...) It serves as a generic container for JSON data with a unique identifier.

type LocalTime added in v1.2.122 

type LocalTime int64

LocalTime represents the time (year, month, day, hour, minute, second) as number in the following format: YYYYMMDDhhmmss. It is useful for storing time in a compact, human-readable integer format that preserves sorting order.

func FromTime added in v1.2.123 

func FromTime(t time.Time) LocalTime

FromTime converts a standard Go time.Time object to LocalTime. The time is converted to UTC before being formatted as YYYYMMDDhhmmss.

func FromTimestamp added in v1.2.123 

func FromTimestamp(ts Timestamp) LocalTime

FromTimestamp converts a Timestamp to LocalTime.

func LocalNow added in v1.2.122 

func LocalNow() LocalTime

LocalNow returns the current UTC time as a LocalTime (YYYYMMDDhhmmss).

func (*LocalTime) Add added in v1.2.122 

func (lt *LocalTime) Add(delta time.Duration) LocalTime

Add adds a duration to the LocalTime and returns a new LocalTime. Note: This implementation treats LocalTime as a simple integer for addition, which might not be correct for date arithmetic. It is recommended to convert to time.Time, add duration, and convert back if date logic is needed.

func (*LocalTime) Split added in v1.2.122 

func (lt *LocalTime) Split() (year, month, day, hours, minutes, seconds int)

Split parses the LocalTime integer into its components: year, month, day, hour, minute, second.

func (*LocalTime) String added in v1.2.122 

func (lt *LocalTime) String(format string) string

String converts LocalTime to a formatted string. It supports custom formatting patterns similar to other time libraries.

func (*LocalTime) Time added in v1.2.122 

func (lt *LocalTime) Time() (result time.Time)

Time converts LocalTime to a standard Go time.Time object in UTC.

func (*LocalTime) Timestamp added in v1.2.123 

func (lt *LocalTime) Timestamp() Timestamp

Timestamp converts LocalTime to a Timestamp (Epoch milliseconds).

type SimpleEntity added in v1.2.41 

type SimpleEntity[T any] struct {
	Value T `json:"value"` // Value is the wrapped entity value
}

SimpleEntity is a generic wrapper to express a primitive type as an Entity. It is useful when you need to treat a simple value (like a string or int) as a full-fledged Entity in the system, for example when passing it to functions that expect an Entity interface.

func (*SimpleEntity[T]) ID added in v1.2.41 

func (e *SimpleEntity[T]) ID() string

func (*SimpleEntity[T]) KEY added in v1.2.41 

func (e *SimpleEntity[T]) KEY() string

func (*SimpleEntity[T]) NAME added in v1.2.41 

func (e *SimpleEntity[T]) NAME() string

func (*SimpleEntity[T]) TABLE added in v1.2.41 

func (e *SimpleEntity[T]) TABLE() string

type TimeDataPoint added in v1.2.35 

type TimeDataPoint[V any] struct {
	Timestamp Timestamp `json:"timestamp"` // Timestamp of the data point
	Value     V         `json:"value"`     // Value of the data point
}

TimeDataPoint represents a generic data point associated with a timestamp.

func NewTimeDataPoint added in v1.2.35 

func NewTimeDataPoint[V any](ts Timestamp, value V) TimeDataPoint[V]

NewTimeDataPoint creates a new TimeDataPoint instance.

func (*TimeDataPoint[V]) String added in v1.2.35 

func (tf *TimeDataPoint[V]) String(format string) string

String returns a string representation of the TimeDataPoint.

type TimeFrame added in v1.2.26 

type TimeFrame struct {
	From Timestamp `json:"from"` // From is the start timestamp
	To   Timestamp `json:"to"`   // To is the end timestamp
}

TimeFrame represents a time interval with a start and end timestamp.

func GetTimeFrame added in v1.2.26 

func GetTimeFrame(from Timestamp, duration time.Duration) TimeFrame

GetTimeFrame creates a new TimeFrame from a start timestamp and a duration.

func NewTimeFrame added in v1.2.26 

func NewTimeFrame(from, to Timestamp) TimeFrame

NewTimeFrame creates a new TimeFrame from start and end timestamps.

func (*TimeFrame) Duration added in v1.2.26 

func (tf *TimeFrame) Duration() time.Duration

Duration returns the duration of the TimeFrame.

func (*TimeFrame) String added in v1.2.26 

func (tf *TimeFrame) String(format string) string

String returns a string representation of the TimeFrame in the format "start - end".

type TimePeriodCode added in v1.2.136 

type TimePeriodCode int

TimePeriodCode represents a code for a time period (e.g., Minute, Hour, Day). @Enum

type TimeSeries added in v1.2.99 

type TimeSeries[T any] struct {
	Name   string             `json:"name"`   // Name of the time series
	Range  TimeFrame          `json:"range"`  // Range covers the start and end time of the series
	Values []TimeDataPoint[T] `json:"values"` // Values contains the data points
}

TimeSeries represents a named collection of data points over a specific time range.

func (*TimeSeries[T]) ID added in v1.2.99 

func (ts *TimeSeries[T]) ID() string

ID returns the time series name as its ID.

func (*TimeSeries[T]) KEY added in v1.2.99 

func (ts *TimeSeries[T]) KEY() string

KEY returns an empty string.

func (*TimeSeries[T]) NAME added in v1.2.99 

func (ts *TimeSeries[T]) NAME() string

NAME returns the time series name.

func (*TimeSeries[T]) SetDataPoint added in v1.2.120 

func (ts *TimeSeries[T]) SetDataPoint(t Timestamp, val T) bool

SetDataPoint updates the value of a data point at a specific timestamp. It returns true if the data point was found and updated, false otherwise.

func (*TimeSeries[T]) TABLE added in v1.2.99 

func (ts *TimeSeries[T]) TABLE() string

TABLE returns an empty string as TimeSeries is typically not a database table itself.

type Timestamp 

type Timestamp int64

Timestamp represents Epoch milliseconds timestamp. It is the primary time representation in the system, allowing for easy serialization and arithmetic.

func EpochNowMillis 

func EpochNowMillis(delta int64) Timestamp

EpochNowMillis returns the current time as Epoch time in milliseconds, with an optional delta.

Parameters:

  • delta: A duration in milliseconds to add to the current time.

Returns:

  • The calculated Timestamp.

func LocalTimestamp added in v1.2.123 

func LocalTimestamp(lt ...LocalTime) Timestamp

LocalTimestamp converts one or more LocalTime values to a Timestamp. If arguments are provided, it converts the first LocalTime to Timestamp. If no arguments are provided, it returns the current time as a Timestamp derived from LocalTime format.

func NewTimestamp added in v1.2.143 

func NewTimestamp(t time.Time) Timestamp

NewTimestamp creates a Timestamp from a standard Go time.Time object.

func Now 

func Now() Timestamp

Now returns the current time as Epoch time in milliseconds.

func (Timestamp) Add added in v1.2.15 

func (ts Timestamp) Add(delta time.Duration) Timestamp

Add adds a duration to the Timestamp and returns a new Timestamp.

func (Timestamp) EndOfDay added in v1.2.144 

func (ts Timestamp) EndOfDay() Timestamp

EndOfDay returns a new Timestamp representing the end of the day (23:59:59.999) for the current timestamp.

func (Timestamp) EndOfHour added in v1.2.144 

func (ts Timestamp) EndOfHour() Timestamp

EndOfHour returns a new Timestamp representing the end of the hour for the current timestamp.

func (Timestamp) EndOfMonth added in v1.2.144 

func (ts Timestamp) EndOfMonth() Timestamp

EndOfMonth returns a new Timestamp representing the end of the month for the current timestamp.

func (Timestamp) LocalString added in v1.2.15 

func (ts Timestamp) LocalString(format string, tz string) string

LocalString converts the Timestamp to a string in a specific timezone.

Parameters:

  • format: The format string.
  • tz: The timezone identifier (e.g., "America/New_York").

Returns:

  • The formatted time string in the specified timezone.

func (Timestamp) StartOfDay added in v1.2.144 

func (ts Timestamp) StartOfDay() Timestamp

StartOfDay returns a new Timestamp representing the start of the day (00:00:00) for the current timestamp.

func (Timestamp) StartOfHour added in v1.2.144 

func (ts Timestamp) StartOfHour() Timestamp

StartOfHour returns a new Timestamp representing the start of the hour for the current timestamp.

func (Timestamp) StartOfMonth added in v1.2.144 

func (ts Timestamp) StartOfMonth() Timestamp

StartOfMonth returns a new Timestamp representing the start of the month for the current timestamp.

func (Timestamp) String added in v1.2.15 

func (ts Timestamp) String(format string) string

String converts the Timestamp to a string using the specified format. If format is empty, it uses RFC3339. It supports custom format strings via convertISO8601Format.

func (Timestamp) Time added in v1.2.15 

func (ts Timestamp) Time() (result time.Time)

Time converts the Timestamp to a standard Go time.Time object.

type Tuple added in v1.2.35 

type Tuple[K, V any] struct {
	Key   K `json:"key"`   // Key is the first element of the tuple
	Value V `json:"value"` // Value is the second element of the tuple
}

Tuple represents a generic key-value pair. It is useful for storing associated data where a full map is not needed or order matters.

Type Parameters:

  • K: The type of the key.
  • V: The type of the value.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.