record

README

Dalgo helper package: record

Contains helpers to simplify working with dalgo records in strongly typed way.

Type WithID[K comparable]

This helper type can/should be used in your own type that packs strongly typed data & ID of your entity. This simplifies strongly typed work with your entities.

Like:

package models4user

import (
	"github.com/dal-go/dalgo/dal"
	"github.com/dal-go/dalgo/record"
)

// UserDto is a type that holds user data
type UserDto struct {
	Name  string
	Email string
}

// User is a type that holds both user data and user ID
type User struct {
	record.WithID[string] // In our case ID is a string

	Dto *UserDto
}

// NewUser creates an object that hold both user data and user ID
func NewUser(id string, dto *UserDto) (user User) {
	user.ID = id
	user.Dto = dto
	user.Key = dal.NewKey("users", dal.WithID(id))
	user.Record = dal.NewRecordWithData(user.Key, dto)
	return user
}

The User.Dto provides strongly typed access to user data. We also can access it via Data() method of record.Record interface but that will require type assertion like:

email := user.Record.Data().(*UserDto).Email // requires manual casting to *UserDto to access email

what is not very convenient. Compare it with:

email := user.Dto.Email // this is strongly typed

Documentation

Index

• func DataToMap(data any) (map[string]any, error)
• func MapToData(target any, src map[string]any) error
• type DataWithID
  • func NewDataWithID[K comparable, D any](id K, key *dal.Key, data D) DataWithID[K, D]
• type Updates
• type WithID
  • func NewWithID[T comparable](id T, key *dal.Key, data any) WithID[T]
  • func (v WithID[K]) String() string
• type WithRecordChanges
  • func (v *WithRecordChanges) ApplyChanges(ctx context.Context, tx dal.ReadwriteTransaction, excludeKeys ...*dal.Key) (err error)
  • func (v *WithRecordChanges) QueueForInsert(records ...dal.Record)
  • func (v *WithRecordChanges) RecordsToInsert() (records []dal.Record)

Functions

func DataToMap

func DataToMap(data any) (map[string]any, error)

DataToMap converts record data into a map[string]any keyed by field name.

A map[string]any is returned unchanged. Any other value (typically a struct or a pointer to a struct) is converted via encoding/json, after which the top-level keys are remapped so a field's `db` tag takes precedence over its `json` tag. This lets file/document adapters that lack a native serializer (unlike the Firestore SDK or scany for SQL) reuse one consistent mapping.

Tag precedence for a field key is: `db` tag, then `json` tag, then field name. `json:"-"` fields are omitted and `,omitempty` is honoured (both via the json round-trip). Nested struct fields are serialized by encoding/json and therefore follow their `json` tags.

func MapToData

func MapToData(target any, src map[string]any) error

MapToData populates target from src. If target is a map[string]any, src is copied into it. Otherwise target must be a pointer (typically to a struct): the `db`-keyed entries in src are remapped back to `json` keys and applied via encoding/json, so values, nested structs and type coercion are handled by the standard library. Tag precedence matches DataToMap: `db`, then `json`, then field name.

Types

type DataWithID

type DataWithID[K comparable, D any] struct {
	WithID[K]
	Data D // we can't use *D here as consumer might want to pass an interface value instead of a pointer
}

func NewDataWithID

func NewDataWithID[K comparable, D any](id K, key *dal.Key, data D) DataWithID[K, D]

type Updates

type Updates struct {
	Record  dal.Record
	Updates []update.Update
}

Updates defines updates for a record

type WithID

type WithID[K comparable] struct {
	ID     K          `json:"id"`               // Unique id of the record in collection
	FullID string     `json:"fullID,omitempty"` // Custom id of the record fully unique across all DB collections
	Key    *dal.Key   `json:"-"`
	Record dal.Record `json:"-"`
}

WithID is a record with a strongly typed ID

func NewWithID

func NewWithID[T comparable](id T, key *dal.Key, data any) WithID[T]

func (WithID[K]) String

func (v WithID[K]) String() string

String returns string representation of a record with an ID

type WithRecordChanges

type WithRecordChanges struct {
	RecordsToUpdate []*Updates
	RecordsToDelete []*dal.Key
	// contains filtered or unexported fields
}

func (*WithRecordChanges) ApplyChanges

func (v *WithRecordChanges) ApplyChanges(ctx context.Context, tx dal.ReadwriteTransaction, excludeKeys ...*dal.Key) (err error)

func (*WithRecordChanges) QueueForInsert

func (v *WithRecordChanges) QueueForInsert(records ...dal.Record)

func (*WithRecordChanges) RecordsToInsert

func (v *WithRecordChanges) RecordsToInsert() (records []dal.Record)