resource

Documentation

Overview

Package resource provides base abstractions for domain entities.

This package defines the core Resource interface that all domain entities should implement. It separates concerns into smaller interfaces (Identifier, Timestamps) for flexibility and provides utilities for working with resources across different transport layers.

Core Interfaces

Resource combines identification and timestamp tracking:

• Identifier: ID(), LID() (local ID), Type()
• Timestamps: CreatedAt(), UpdatedAt(), DeletedAt() (soft delete support)

Usage

Creating a new resource:

player := resource.New(
    resource.WithID(uuid.New().String()),
    resource.WithType("player"),
    resource.WithCreatedAt(time.Now()),
    resource.WithUpdatedAt(time.Now()),
)

Creating an identifier reference (lightweight):

playerRef := resource.NewIdentifier("player-123", resource.Type("player"))

Updating a resource:

updated := resource.Update(player,
    resource.WithUpdatedAt(time.Now()),
)

Protocol Buffer Support

Convert to/from protobuf for gRPC services:

// To proto
pb := resource.ToProto(player)

// From proto
player := resource.FromProto(pb)

// Identifiers
identifierPb := resource.IdentifierToProto(playerRef)

Testing

Use resourcetest package for creating test fixtures:

import "github.com/fromforgesoftware/forge/go/kit/resource/resourcetest"

testPlayer := resourcetest.New(
    resourcetest.WithType("player"),
    resourcetest.WithID("player-123"),
)

Soft Deletes

Resources support soft deletion via the DeletedAt timestamp:

now := time.Now()
deleted := resource.Update(player,
    resource.WithDeletedAt(&now),
)

if deleted.DeletedAt() != nil {
    // Resource is soft-deleted
}

Type Safety

Use strongly-typed resource types to avoid string errors:

const (
    TypePlayer = resource.Type("player")
    TypeGuild  = resource.Type("guild")
    TypeItem   = resource.Type("item")
)

Index

• func FullOrOnlyIdentifierDTO[I, O Resource](identifier Identifier, mapFunc func(I) O, ...) O
• func IDToInt(id string) int
• func IDToUint64(id string) uint64
• func IdentifierToProto(r Identifier) *resourcepb.ResourceIdentifier
• func IdentifiersToProto(rs []Identifier) []*resourcepb.ResourceIdentifier
• func ListResponseToDTO[DTO any, R any](resMapper func(R) DTO) func(res ListResponse[R]) *ListResponseDTO[DTO]
• func NewEmptyListResponse[T any]() *listRes[T]
• func NewListResponse[T any](items []T, count int) *listRes[T]
• func RestIdentifierToDTO(r Identifier) *identifierDTO
• func ToProto(r Resource) *resourcepb.Resource
• func Update(res Resource, opts ...resourceOption) *resource
• func WithCreateOp(c *fullOrOnlyIdentifierDTOConfig)
• func WithCreatedAt(createdAt time.Time) resourceOption
• func WithDeletedAt(deletedAt *time.Time) resourceOption
• func WithID(id string) resourceOption
• func WithLID(lid string) resourceOption
• func WithType(kind Type) resourceOption
• func WithUpdateOp(c *fullOrOnlyIdentifierDTOConfig)
• func WithUpdatedAt(updatedAt time.Time) resourceOption
• type FullOrOnlyIdentifierDTOConfigOpt
• type Identifier
  • func IdentifierFromProto(r *resourcepb.ResourceIdentifier) Identifier
  • func NewIdentifier(id string, kind Type) Identifier
• type ListResponse
• type ListResponseDTO
  • func (l *ListResponseDTO[DTO]) Results() []DTO
• type PaginationDTO
• type RelationshipDTO
  • func RelationshipToDTO(opts ...RelationshipDTOOpt) *RelationshipDTO
• type RelationshipDTOOpt
  • func RelFromIDAndType(id string, kind Type) RelationshipDTOOpt
  • func RelFromIdentifier(id Identifier) RelationshipDTOOpt
• type Resource
  • func FromProto(r *resourcepb.Resource) Resource
  • func New(opts ...resourceOption) Resource
• type RestDTO
  • func ToRestDTO(r Resource) RestDTO
  • func (dto *RestDTO) CreatedAt() time.Time
  • func (dto *RestDTO) DeletedAt() *time.Time
  • func (dto *RestDTO) ID() string
  • func (dto *RestDTO) LID() string
  • func (dto *RestDTO) Type() Type
  • func (dto *RestDTO) UpdatedAt() time.Time
• type TimestampDTO
  • func TimestampToDTO(t Timestamps) *TimestampDTO
• type Timestamps
• type Type
  • func (t Type) String() string

Functions

func FullOrOnlyIdentifierDTO

func FullOrOnlyIdentifierDTO[I, O Resource](
	identifier Identifier, mapFunc func(I) O,
	opts ...FullOrOnlyIdentifierDTOConfigOpt,
) O

func IDToInt

func IDToInt(id string) int

func IDToUint64

func IDToUint64(id string) uint64

func IdentifierToProto

func IdentifierToProto(r Identifier) *resourcepb.ResourceIdentifier

func IdentifiersToProto

func IdentifiersToProto(rs []Identifier) []*resourcepb.ResourceIdentifier

func ListResponseToDTO

func ListResponseToDTO[DTO any, R any](
	resMapper func(R) DTO,
) func(res ListResponse[R]) *ListResponseDTO[DTO]

func NewEmptyListResponse

func NewEmptyListResponse[T any]() *listRes[T]

func NewListResponse

func NewListResponse[T any](items []T, count int) *listRes[T]

func RestIdentifierToDTO

func RestIdentifierToDTO(r Identifier) *identifierDTO

func ToProto

func ToProto(r Resource) *resourcepb.Resource

func Update

func Update(res Resource, opts ...resourceOption) *resource

func WithCreateOp

func WithCreateOp(c *fullOrOnlyIdentifierDTOConfig)

func WithCreatedAt

func WithCreatedAt(createdAt time.Time) resourceOption

func WithDeletedAt

func WithDeletedAt(deletedAt *time.Time) resourceOption

func WithID

func WithID(id string) resourceOption

func WithLID

func WithLID(lid string) resourceOption

func WithType

func WithType(kind Type) resourceOption

func WithUpdateOp

func WithUpdateOp(c *fullOrOnlyIdentifierDTOConfig)

func WithUpdatedAt

func WithUpdatedAt(updatedAt time.Time) resourceOption

Types

type FullOrOnlyIdentifierDTOConfigOpt

type FullOrOnlyIdentifierDTOConfigOpt func(c *fullOrOnlyIdentifierDTOConfig)

type Identifier

type Identifier interface {
	ID() string
	LID() string
	Type() Type
}

func IdentifierFromProto

func IdentifierFromProto(r *resourcepb.ResourceIdentifier) Identifier

func NewIdentifier

func NewIdentifier(id string, kind Type) Identifier

type ListResponse

type ListResponse[T any] interface {
	Results() []T
	TotalCount() int
}

type ListResponseDTO

type ListResponseDTO[DTO any] struct {
	RResults   []DTO          `json:"results"`
	Pagination *PaginationDTO `json:"pagination"`
}

func (*ListResponseDTO[DTO]) Results

func (l *ListResponseDTO[DTO]) Results() []DTO

Results returns the list of DTOs, implementing jsonapi.ListResponse[DTO]

type PaginationDTO

type PaginationDTO struct {
	TotalCount int `json:"totalCount"`
}

type RelationshipDTO

type RelationshipDTO struct {
	RestDTO
}

func RelationshipToDTO

func RelationshipToDTO(opts ...RelationshipDTOOpt) *RelationshipDTO

type RelationshipDTOOpt

type RelationshipDTOOpt func(r *RelationshipDTO)

func RelFromIDAndType

func RelFromIDAndType(id string, kind Type) RelationshipDTOOpt

func RelFromIdentifier

func RelFromIdentifier(id Identifier) RelationshipDTOOpt

type Resource

type Resource interface {
	Identifier
	Timestamps
}

func FromProto

func FromProto(r *resourcepb.Resource) Resource

func New

func New(opts ...resourceOption) Resource

type RestDTO

type RestDTO struct {
	RID         string        `jsonapi:"primary"`
	RLID        string        `jsonapi:"client-id,omitempty"`
	RType       Type          `jsonapi:"type"`
	RTimestamps *TimestampDTO `jsonapi:"attr,timestamps,omitempty"`
}

func ToRestDTO

func ToRestDTO(r Resource) RestDTO

func (*RestDTO) CreatedAt

func (dto *RestDTO) CreatedAt() time.Time

func (*RestDTO) DeletedAt

func (dto *RestDTO) DeletedAt() *time.Time

func (*RestDTO) ID

func (dto *RestDTO) ID() string

func (*RestDTO) LID

func (dto *RestDTO) LID() string

func (*RestDTO) Type

func (dto *RestDTO) Type() Type

func (*RestDTO) UpdatedAt

func (dto *RestDTO) UpdatedAt() time.Time

type TimestampDTO

type TimestampDTO struct {
	RCreatedAt time.Time  `jsonapi:"attr,createdAt"`
	RUpdatedAt time.Time  `jsonapi:"attr,updatedAt"`
	RDeletedAt *time.Time `jsonapi:"attr,deletedAt,omitempty"`
}

func TimestampToDTO

func TimestampToDTO(t Timestamps) *TimestampDTO

type Timestamps

type Timestamps interface {
	CreatedAt() time.Time
	UpdatedAt() time.Time
	DeletedAt() *time.Time
}

type Type

type Type string

func (Type) String

func (t Type) String() string