feat(datastore) remove generics from the top level api (#149)

This PR introduces a leaner custom metadata handling model by replacing
generics with `any`. While generics are still used to define interfaces,
we now replace the use of generics for contract and environment metadata
with any. This simplifies the API and removes the need for two
conversion steps per changeset. Users can continue to work with their
own metadata types. The only trade-off is that when reading from the
datastore (e.g., after a Get()), they’ll need to convert from any, which
is easily handled using the provided `As` helper. Overall, this change
reduces boilerplate and improves usability without sacrificing
flexibility.

Author: giogam

.changeset/purple-needles-retire.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": patch
+---
+
+feat(datastore) remove generics from the top level api

datastore/contract_metadata.go

@@ -6,30 +6,30 @@ var ErrContractMetadataNotFound = errors.New("no contract metadata record can be
 var ErrContractMetadataExists = errors.New("a contract metadata record with the supplied key already exists")
 
 // ContractMetadata implements the Record interface
-var _ UniqueRecord[ContractMetadataKey, ContractMetadata[DefaultMetadata]] = ContractMetadata[DefaultMetadata]{}
+var _ UniqueRecord[ContractMetadataKey, ContractMetadata] = ContractMetadata{}
 
 // ContractMetadata is a generic struct that holds the metadata for a contract on a specific chain.
 // It implements the Record interface and is used to store contract metadata in the datastore.
 // The metadata is generic and can be of any type that implements the Cloneable interface.
-type ContractMetadata[M any] struct {
+type ContractMetadata struct {
 	// Address is the address of the contract on the chain.
 	Address string `json:"address"`
 	// ChainSelector is the chain-selector of the chain where the contract is deployed.
 	ChainSelector uint64 `json:"chainSelector"`
 	// Metadata is the metadata associated with the contract.
 	// It is a generic type that can be of any type that implements the Cloneable interface.
-	Metadata M `json:"metadata"`
+	Metadata any `json:"metadata"`
 }
 
 // Clone creates a copy of the ContractMetadata.
 // The Metadata field is cloned using the Clone method of the Cloneable interface.
-func (r ContractMetadata[M]) Clone() (ContractMetadata[M], error) {
+func (r ContractMetadata) Clone() (ContractMetadata, error) {
 	metaClone, err := clone(r.Metadata)
 	if err != nil {
-		return ContractMetadata[M]{}, err
+		return ContractMetadata{}, err
 	}
 
-	return ContractMetadata[M]{
+	return ContractMetadata{
 		ChainSelector: r.ChainSelector,
 		Address:       r.Address,
 		Metadata:      metaClone,
@@ -38,6 +38,6 @@ func (r ContractMetadata[M]) Clone() (ContractMetadata[M], error) {
 
 // Key returns the ContractMetadataKey for the ContractMetadata.
 // It is used to uniquely identify the contract metadata in the datastore.
-func (r ContractMetadata[M]) Key() ContractMetadataKey {
+func (r ContractMetadata) Key() ContractMetadataKey {
 	return NewContractMetadataKey(r.ChainSelector, r.Address)
 }

datastore/contract_metadata_test.go

@@ -4,41 +4,55 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/require"
+
+	chain_selectors "github.com/smartcontractkit/chain-selectors"
 )
 
 func TestContractMetadata_Clone(t *testing.T) {
 	t.Parallel()
 
-	original := ContractMetadata[DefaultMetadata]{
+	original := ContractMetadata{
 		ChainSelector: 1,
 		Address:       "0x123",
-		Metadata:      DefaultMetadata{Data: "test data"},
+		Metadata: testMetadata{
+			Field:         "test field",
+			ChainSelector: chain_selectors.APTOS_MAINNET.Selector,
+		},
 	}
 
 	cloned, err := original.Clone()
 	require.NoError(t, err, "Clone should not return an error")
 
 	require.Equal(t, original.ChainSelector, cloned.ChainSelector)
 	require.Equal(t, original.Address, cloned.Address)
-	require.Equal(t, original.Metadata, cloned.Metadata)
+
+	concrete, err := As[testMetadata](cloned.Metadata)
+	require.NoError(t, err, "As should not return an error for CustomMetadata")
+	require.Equal(t, original.Metadata, concrete)
 
 	// Modify the original and ensure the cloned remains unchanged
 	original.ChainSelector = 2
 	original.Address = "0x456"
-	original.Metadata = DefaultMetadata{Data: "updated data"}
+	original.Metadata = testMetadata{
+		Field:         "updated field",
+		ChainSelector: chain_selectors.APTOS_MAINNET.Selector,
+	}
 
 	require.NotEqual(t, original.ChainSelector, cloned.ChainSelector)
 	require.NotEqual(t, original.Address, cloned.Address)
-	require.NotEqual(t, original.Metadata, cloned.Metadata)
+
+	concrete, err = As[testMetadata](cloned.Metadata)
+	require.NoError(t, err, "As should not return an error for CustomMetadata")
+	require.NotEqual(t, original.Metadata, concrete, "Cloned metadata should not be equal to modified original")
 }
 
 func TestContractMetadata_Key(t *testing.T) {
 	t.Parallel()
 
-	metadata := ContractMetadata[DefaultMetadata]{
+	metadata := ContractMetadata{
 		ChainSelector: 1,
 		Address:       "0x123",
-		Metadata:      DefaultMetadata{Data: "test data"},
+		Metadata:      testMetadata{Field: "test data", ChainSelector: 0},
 	}
 
 	key := metadata.Key()

datastore/default_metadata.go

@@ -4,22 +4,22 @@ import "errors"
 
 var ErrEnvMetadataNotSet = errors.New("no environment metadata set")
 
-type EnvMetadata[M any] struct {
+type EnvMetadata struct {
 	// Metadata is the metadata associated with the domain and environment.
 	// It is a generic type that can be of any type that implements the Cloneable interface.
-	Metadata M `json:"metadata"`
+	Metadata any `json:"metadata"`
 }
 
 // Clone creates a copy of the EnvMetadata.
 // The Metadata field is cloned using the Clone method of the Cloneable interface.
-func (r EnvMetadata[M]) Clone() (EnvMetadata[M], error) {
+func (r EnvMetadata) Clone() (EnvMetadata, error) {
 	metaClone, err := clone(r.Metadata)
 	if err != nil {
 		// If cloning fails, we return an empty EnvMetadata with the error.
-		return EnvMetadata[M]{}, err
+		return EnvMetadata{}, err
 	}
 
-	return EnvMetadata[M]{
+	return EnvMetadata{
 		Metadata: metaClone,
 	}, nil
 }

datastore/env_metadata.go

@@ -9,13 +9,24 @@ import (
 func TestEnvMetadata_Clone(t *testing.T) {
 	t.Parallel()
 
-	original := EnvMetadata[DefaultMetadata]{
-		Metadata: DefaultMetadata{Data: "test-value"},
-	}
+	var (
+		metaOne  = testMetadata{Field: "test-value-one", ChainSelector: 0}
+		metaTwo  = testMetadata{Field: "test-value-two", ChainSelector: 0}
+		original = EnvMetadata{
+			Metadata: metaOne,
+		}
+	)
 
 	cloned, err := original.Clone()
 	require.NoError(t, err, "Clone should not return an error")
 
-	require.Equal(t, original.Metadata, cloned.Metadata)
-	require.NotSame(t, &original.Metadata, &cloned.Metadata) // Ensure Metadata is a deep copy
+	concrete, err := As[testMetadata](cloned.Metadata)
+	require.NoError(t, err, "As should not return an error for CustomMetadata")
+	require.Equal(t, metaOne, concrete)
+
+	original.Metadata = metaTwo
+
+	concreteTwo, err := As[testMetadata](original.Metadata)
+	require.NoError(t, err, "As should not return an error for CustomMetadata after modification")
+	require.NotEqual(t, concrete, concreteTwo, "Cloned metadata should not be equal to modified original metadata")
 }

datastore/env_metadata_test.go

@@ -75,9 +75,9 @@ func AddressRefByQualifier(qualifier string) FilterFunc[AddressRefKey, AddressRe
 }
 
 // ContractMetadataByChainSelector returns a filter that only includes records with the provided chain.
-func ContractMetadataByChainSelector[M any](chainSelector uint64) FilterFunc[ContractMetadataKey, ContractMetadata[M]] {
-	return func(records []ContractMetadata[M]) []ContractMetadata[M] {
-		filtered := make([]ContractMetadata[M], 0, len(records)) // Pre-allocate capacity
+func ContractMetadataByChainSelector(chainSelector uint64) FilterFunc[ContractMetadataKey, ContractMetadata] {
+	return func(records []ContractMetadata) []ContractMetadata {
+		filtered := make([]ContractMetadata, 0, len(records)) // Pre-allocate capacity
 		for _, record := range records {
 			if record.ChainSelector == chainSelector {
 				filtered = append(filtered, record)

datastore/filters.go

@@ -351,56 +351,56 @@ func TestContractMetadataByChainSelector(t *testing.T) {
 	t.Parallel()
 
 	var (
-		recordOne = ContractMetadata[DefaultMetadata]{
+		recordOne = ContractMetadata{
 			ChainSelector: 1,
-			Metadata:      DefaultMetadata{Data: "Record1"},
+			Metadata:      testMetadata{Field: "Record1", ChainSelector: 0},
 		}
-		recordTwo = ContractMetadata[DefaultMetadata]{
+		recordTwo = ContractMetadata{
 			ChainSelector: 2,
-			Metadata:      DefaultMetadata{Data: "Record2"},
+			Metadata:      testMetadata{Field: "Record2", ChainSelector: 0},
 		}
-		recordThree = ContractMetadata[DefaultMetadata]{
+		recordThree = ContractMetadata{
 			ChainSelector: 1,
-			Metadata:      DefaultMetadata{Data: "Record3"},
+			Metadata:      testMetadata{Field: "Record3", ChainSelector: 0},
 		}
 	)
 
 	tests := []struct {
 		name           string
-		givenState     []ContractMetadata[DefaultMetadata]
+		givenState     []ContractMetadata
 		giveChain      uint64
-		expectedResult []ContractMetadata[DefaultMetadata]
+		expectedResult []ContractMetadata
 	}{
 		{
 			name: "success: returns records with given chain",
-			givenState: []ContractMetadata[DefaultMetadata]{
+			givenState: []ContractMetadata{
 				recordOne,
 				recordTwo,
 				recordThree,
 			},
 			giveChain: 1,
-			expectedResult: []ContractMetadata[DefaultMetadata]{
+			expectedResult: []ContractMetadata{
 				recordOne,
 				recordThree,
 			},
 		},
 		{
 			name: "success: returns no records with given chain",
-			givenState: []ContractMetadata[DefaultMetadata]{
+			givenState: []ContractMetadata{
 				recordOne,
 				recordTwo,
 				recordThree,
 			},
 			giveChain:      3,
-			expectedResult: []ContractMetadata[DefaultMetadata]{},
+			expectedResult: []ContractMetadata{},
 		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 
-			filter := ContractMetadataByChainSelector[DefaultMetadata](tt.giveChain)
+			filter := ContractMetadataByChainSelector(tt.giveChain)
 			filteredRecords := filter(tt.givenState)
 			assert.Equal(t, tt.expectedResult, filteredRecords)
 		})

datastore/filters_test.go

@@ -6,54 +6,54 @@ import (
 
 // ContractMetadataStore is an interface that represents an immutable view over a set
 // of ContractMetadata records identified by ContractMetadataKey.
-type ContractMetadataStore[M any] interface {
-	Store[ContractMetadataKey, ContractMetadata[M]]
+type ContractMetadataStore interface {
+	Store[ContractMetadataKey, ContractMetadata]
 }
 
 // MutableContractMetadataStore is an interface that represents a mutable ContractMetadataStore
 // of ContractMetadata records identified by ContractMetadataKey.
-type MutableContractMetadataStore[M any] interface {
-	MutableStore[ContractMetadataKey, ContractMetadata[M]]
+type MutableContractMetadataStore interface {
+	MutableStore[ContractMetadataKey, ContractMetadata]
 }
 
 // MemoryContractMetadataStore is an in-memory implementation of the ContractMetadataStore and
 // MutableContractMetadataStore interfaces.
-type MemoryContractMetadataStore[M any] struct {
+type MemoryContractMetadataStore struct {
 	mu      sync.RWMutex
-	Records []ContractMetadata[M] `json:"records"`
+	Records []ContractMetadata `json:"records"`
 }
 
 // MemoryContractMetadataStore implements ContractMetadataStore interface.
-var _ ContractMetadataStore[DefaultMetadata] = &MemoryContractMetadataStore[DefaultMetadata]{}
+var _ ContractMetadataStore = &MemoryContractMetadataStore{}
 
 // MemoryContractMetadataStore implements MutableContractMetadataStore interface.
-var _ MutableContractMetadataStore[DefaultMetadata] = &MemoryContractMetadataStore[DefaultMetadata]{}
+var _ MutableContractMetadataStore = &MemoryContractMetadataStore{}
 
 // NewMemoryContractMetadataStore creates a new MemoryContractMetadataStore instance.
 // It is a generic function that takes a type parameter M which must implement the Cloneable interface.
-func NewMemoryContractMetadataStore[M any]() *MemoryContractMetadataStore[M] {
-	return &MemoryContractMetadataStore[M]{Records: []ContractMetadata[M]{}}
+func NewMemoryContractMetadataStore() *MemoryContractMetadataStore {
+	return &MemoryContractMetadataStore{Records: []ContractMetadata{}}
 }
 
 // Get returns the ContractMetadata for the provided key, or an error if no such record exists.
-func (s *MemoryContractMetadataStore[M]) Get(key ContractMetadataKey) (ContractMetadata[M], error) {
+func (s *MemoryContractMetadataStore) Get(key ContractMetadataKey) (ContractMetadata, error) {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
 
 	idx := s.indexOf(key)
 	if idx == -1 {
-		return ContractMetadata[M]{}, ErrContractMetadataNotFound
+		return ContractMetadata{}, ErrContractMetadataNotFound
 	}
 
 	return s.Records[idx].Clone()
 }
 
 // Fetch returns a copy of all ContractMetadata in the store.
-func (s *MemoryContractMetadataStore[M]) Fetch() ([]ContractMetadata[M], error) {
+func (s *MemoryContractMetadataStore) Fetch() ([]ContractMetadata, error) {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
 
-	records := []ContractMetadata[M]{}
+	records := []ContractMetadata{}
 	for _, record := range s.Records {
 		clone, err := record.Clone()
 		if err != nil {
@@ -68,11 +68,11 @@ func (s *MemoryContractMetadataStore[M]) Fetch() ([]ContractMetadata[M], error)
 // Filter returns a copy of all ContractMetadata in the store that pass all of the provided filters.
 // Filters are applied in the order they are provided.
 // If no filters are provided, all records are returned.
-func (s *MemoryContractMetadataStore[M]) Filter(filters ...FilterFunc[ContractMetadataKey, ContractMetadata[M]]) []ContractMetadata[M] {
+func (s *MemoryContractMetadataStore) Filter(filters ...FilterFunc[ContractMetadataKey, ContractMetadata]) []ContractMetadata {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
 
-	records := append([]ContractMetadata[M]{}, s.Records...)
+	records := append([]ContractMetadata{}, s.Records...)
 	for _, filter := range filters {
 		records = filter(records)
 	}
@@ -81,7 +81,7 @@ func (s *MemoryContractMetadataStore[M]) Filter(filters ...FilterFunc[ContractMe
 }
 
 // indexOf returns the index of the record with the provided key, or -1 if no such record exists.
-func (s *MemoryContractMetadataStore[M]) indexOf(key ContractMetadataKey) int {
+func (s *MemoryContractMetadataStore) indexOf(key ContractMetadataKey) int {
 	for i, record := range s.Records {
 		if record.Key().Equals(key) {
 			return i
@@ -93,7 +93,7 @@ func (s *MemoryContractMetadataStore[M]) indexOf(key ContractMetadataKey) int {
 
 // Add inserts a new record into the store.
 // If a record with the same key already exists, an error is returned.
-func (s *MemoryContractMetadataStore[M]) Add(record ContractMetadata[M]) error {
+func (s *MemoryContractMetadataStore) Add(record ContractMetadata) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 
@@ -108,7 +108,7 @@ func (s *MemoryContractMetadataStore[M]) Add(record ContractMetadata[M]) error {
 
 // Upsert inserts a new record into the store if no record with the same key already exists.
 // If a record with the same key already exists, it is updated.
-func (s *MemoryContractMetadataStore[M]) Upsert(record ContractMetadata[M]) error {
+func (s *MemoryContractMetadataStore) Upsert(record ContractMetadata) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 
@@ -125,7 +125,7 @@ func (s *MemoryContractMetadataStore[M]) Upsert(record ContractMetadata[M]) erro
 // Update edits an existing record whose fields match the primary key elements of the supplied ContractMetadata, with
 // the non-primary-key values of the supplied ContractMetadata.
 // If no such record exists, an error is returned.
-func (s *MemoryContractMetadataStore[M]) Update(record ContractMetadata[M]) error {
+func (s *MemoryContractMetadataStore) Update(record ContractMetadata) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 
@@ -140,7 +140,7 @@ func (s *MemoryContractMetadataStore[M]) Update(record ContractMetadata[M]) erro
 
 // Delete deletes an existing record whose primary key elements match the supplied ContractMetadata, returning an error if no
 // such record exists.
-func (s *MemoryContractMetadataStore[M]) Delete(key ContractMetadataKey) error {
+func (s *MemoryContractMetadataStore) Delete(key ContractMetadataKey) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()