README
¶
Data Object 
A data object is a special purpose structure that is designed to hold data and track the changes to allow efficient serialization to a data store.
It follows the following principles:
- Has a default, non-argument constructor
- Has a unique identifier (ID) allowing to safely find the object among any other
- All the fields are private, thus non-modifiable from outside
- The fields are only accessed via public setter (mutator) and getter (accessor) methods
- All changes are tracked, and returned on request as a map of type map[string]string
- All data can be returned on request as a map of type map[string]string
Any object can be considered a data object as long as it adheres to the above principles, regardless of its specific implementation.
The implementation in this repo is just one way to implement the above principles. Other variations are possible to suit specific needs.
The concept is a bit similar to a POJO and a Java Bean.
Usage
This is a full fledged example of a User data object taken from real life.
The example shows how to create new data object, set and get fields. Add helper methods to work with the fields.
Optional ORM-like relationship methods are also included. Use these with caution as these may create dependencies (i.e. with your services, repos, etc) that you may not want and need.
package models
import (
"github.com/gouniverse/dataobject"
"github.com/gouniverse/uid"
"github.com/golang-module/carbon/v2"
)
// User is a data object
type User struct {
dataobject.DataObject
}
// ============================= CONSTRUCTORS =============================
// NewUser instantiates a new user
func NewUser() *User {
o := &User{}
o.SetID(uid.HumanUid())
o.SetStatus("active")
o.SetCreatedAt(carbon.Now(carbon.UTC).ToDateTimeString(carbon.UTC))
o.SetUpdatedAt(carbon.Now(carbon.UTC).ToDateTimeString(carbon.UTC))
return o
}
// NewUserFromExistingData helper method to hydrate an existing user data object
func NewUserFromExistingData(data map[string]string) *User {
o := &User{}
o.Hydrate(data)
return o
}
// ======================== RELATIONS/ORM (OPTIONAL) ===========================
func (o *User) Messages() []Messages {
return NewMessageService.GetUserMessages(o.GetID())
}
func (o *User) Create() error {
return NewUserService.Create(o)
}
func (o *User) Update() error {
if !o.IsDirty() {
return nil // object has not been changed
}
return NewUserService.Update(o)
}
// ================================ METHODS ====================================
func (o *User) IsActive() bool {
return o.Status() == "active"
}
// ============================ GETTERS AND SETTERS ============================
func (o *User) CreatedAt() string {
return o.Get("created_at")
}
func (o *User) CreatedAtCarbon() carbon.Carbon {
return carbon.Parse(o.CreatedAt(), carbon.UTC)
}
func (o *User) SetCreatedAt(createdAt string) *User {
o.Set("created_at", createdAt)
return o
}
func (o *User) FirstName() string {
return o.Get("first_name")
}
func (o *User) SetFirstName(firstName string) *User {
o.Set("first_name", firstName)
return o
}
func (o *User) LastName() string {
return o.Get("last_name")
}
func (o *User) SetLastName(lastName string) *User {
o.Set("last_name", lastName)
return o
}
func (o *User) MiddleNames() string {
return o.Get("middle_names")
}
func (o *User) SetMiddleNames(middleNames string) *User {
o.Set("middle_names", middleNames)
return o
}
func (o *User) Status() string {
return o.Get("status")
}
func (o *User) SetStatus(status string) *User {
o.Set("status", status)
return o
}
func (o *User) UpdatedAt() string {
return o.Get("updated_at")
}
func (o *User) UpdatedAtCarbon() carbon.Carbon {
return carbon.Parse(o.UpdatedAt(), carbon.UTC)
}
func (o *User) SetUpdatedAt(updatedAt string) *User {
o.Set("updated_at", updatedAt)
return o
}
For an object using the above specifications
// Create new user with autogenerated default ID
user := NewUser()
// Create new user with already existing data (i.e. from database)
user := NewUserFromData(data)
// returns the ID of the object
id := user.ID()
// example setter method
user.SetFirstName("John")
// example getter method
firstName := user.FirstName()
// find if the object has been modified
isDirty := user.IsDirty()
// reurns the changed data
dataChanged := user.DataChanged()
// reurns all the data
data := user.Data()
Saving data
Saving the data is left to the end user, as it is specific for each data store.
Some stores (i.e. relational databases) allow to only change specific fields, which is why the DataChanged() getter method should be used to identify the changed fields, then only save the changes efficiently.
func SaveUserChanges(user User) bool {
if !user.IsDirty() {
return true
}
changedData := user.DataChanged()
return save(changedData)
}
Other stores (i.e. document stores, file stores) save all the fields each time, which is where the Data() getter method should be used
func SaveFullUser(user User) bool {
if !user.IsDirty() {
return true
}
allData := user.Data()
return save(allData)
}
Serialize to JSON
jsonString, err := user.ToJSON()
if err != nil {
log.Fatal("Error serializing")
}
log.Println(jsonString)
Deserialize from JSON
user, err := NewDataObjectFromJSON(jsonString)
if err != nil {
log.Fatal("Error deserializing")
}
user.Get("first_name")
Documentation
¶
Index ¶
- type DataObject
- func (do *DataObject) Data() map[string]string
- func (do *DataObject) DataChanged() map[string]string
- func (do *DataObject) Get(key string) string
- func (do *DataObject) Hydrate(data map[string]string)
- func (do *DataObject) ID() string
- func (do *DataObject) Init()
- func (do *DataObject) IsDirty() bool
- func (do *DataObject) MarkAsNotDirty()
- func (do *DataObject) Set(key string, value string)
- func (do *DataObject) SetData(data map[string]string)
- func (do *DataObject) SetID(id string)
- func (do *DataObject) ToJSON() (string, error)
- type DataObjectInterface
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DataObject ¶
type DataObject struct {
// contains filtered or unexported fields
}
func NewDataObject ¶
func NewDataObject() *DataObject
NewDataObject creates a new data object and generates an ID
func NewDataObjectFromExistingData ¶
func NewDataObjectFromExistingData(data map[string]string) *DataObject
NewDataObjectFromExistingData creates a new data object and hydrates it with the passed data
func NewDataObjectFromJSON ¶ added in v0.1.0
func NewDataObjectFromJSON(jsonString string) (do *DataObject, err error)
func (*DataObject) Data ¶
func (do *DataObject) Data() map[string]string
Data returns all the data of the object
func (*DataObject) DataChanged ¶
func (do *DataObject) DataChanged() map[string]string
DataChanged returns only the modified data
func (*DataObject) Hydrate ¶
func (do *DataObject) Hydrate(data map[string]string)
Hydrate sets the data for the object without marking it as dirty
func (*DataObject) Init ¶
func (do *DataObject) Init()
Init initializes the data object if it is not already initialized
func (*DataObject) IsDirty ¶
func (do *DataObject) IsDirty() bool
IsDirty returns if data has been modified
func (*DataObject) MarkAsNotDirty ¶ added in v0.2.0
func (do *DataObject) MarkAsNotDirty()
MarkAsNotDirty marks the object as not dirty
func (*DataObject) Set ¶
func (do *DataObject) Set(key string, value string)
Set helper setter method
func (*DataObject) SetData ¶
func (do *DataObject) SetData(data map[string]string)
SetData sets the data for the object and marks it as dirty see Hydrate for assignment without marking as dirty
func (*DataObject) ToJSON ¶ added in v0.1.0
func (do *DataObject) ToJSON() (string, error)
ToJSON converts the DataObject to a JSON string
Returns: - the JSON string representation of the DataObject - an error if any
type DataObjectInterface ¶
type DataObjectInterface interface {
// ID returns the ID of the object
ID() string
// SetID sets the ID of the object
SetID(id string)
// GetData returns the data for the object
Data() map[string]string
// GetChangedData returns the data that has been changed since the last hydration
DataChanged() map[string]string
// Hydrates the data object with data
Hydrate(map[string]string)
}
DataObjectInterface is an interface for a data object
Source Files