feat: Add Table-Store (aka ORM) package - Index and Iterator

types/errors/errors.go

@@ -166,8 +166,8 @@ var (
 	// ErrORMUniqueConstraint defines an error when a value already exists at a given key
 	ErrORMUniqueConstraint = Register(ormCodespace, 44, "unique constraint violation")
 
-	// ErrORMEmptyModel defines an error when an empty model is provided for building a table
-	ErrORMEmptyModel = Register(ormCodespace, 45, "invalid argument")
+	// ErrORMInvalidArgument defines an error when an invalid argument is provided as part of ORM functions
+	ErrORMInvalidArgument = Register(ormCodespace, 45, "invalid argument")
 
 	// ErrORMKeyMaxLength defines an error when a key exceeds max length
 	ErrORMKeyMaxLength = Register(ormCodespace, 46, "key exceeds max length")

x/group/internal/orm/auto_uint64.go

@@ -73,3 +73,36 @@ func (a AutoUInt64Table) GetOne(store sdk.KVStore, rowID uint64, dest codec.Prot
 	}
 	return rawRowID, nil
 }
+
+// PrefixScan returns an Iterator over a domain of keys in ascending order. End is exclusive.
+// Start is an MultiKeyIndex key or prefix. It must be less than end, or the Iterator is invalid and error is returned.
+// Iterator must be closed by caller.
+// To iterate over entire domain, use PrefixScan(nil, nil)
+//
+// WARNING: The use of a PrefixScan can be very expensive in terms of Gas. Please make sure you do not expose
+// this as an endpoint to the public without further limits.
+// Example:
+//			it, err := idx.PrefixScan(ctx, start, end)
+//			if err !=nil {
+//				return err
+//			}
+//			const defaultLimit = 20
+//			it = LimitIterator(it, defaultLimit)
+//
+// CONTRACT: No writes may happen within a domain while an iterator exists over it.
+func (a AutoUInt64Table) PrefixScan(store sdk.KVStore, start, end uint64) (Iterator, error) {
+	return a.table.PrefixScan(store, EncodeSequence(start), EncodeSequence(end))
+}
+
+// ReversePrefixScan returns an Iterator over a domain of keys in descending order. End is exclusive.
+// Start is an MultiKeyIndex key or prefix. It must be less than end, or the Iterator is invalid  and error is returned.
+// Iterator must be closed by caller.
+// To iterate over entire domain, use PrefixScan(nil, nil)
+//
+// WARNING: The use of a ReversePrefixScan can be very expensive in terms of Gas. Please make sure you do not expose
+// this as an endpoint to the public without further limits. See `LimitIterator`
+//
+// CONTRACT: No writes may happen within a domain while an iterator exists over it.
+func (a AutoUInt64Table) ReversePrefixScan(store sdk.KVStore, start uint64, end uint64) (Iterator, error) {
+	return a.table.ReversePrefixScan(store, EncodeSequence(start), EncodeSequence(end))
+}

x/group/internal/orm/auto_uint64_test.go

@@ -0,0 +1,163 @@
+package orm
+
+import (
+	"math"
+	"testing"
+
+	"github.com/cosmos/cosmos-sdk/codec"
+	"github.com/cosmos/cosmos-sdk/codec/types"
+	"github.com/cosmos/cosmos-sdk/testutil/testdata"
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/cosmos/cosmos-sdk/types/errors"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAutoUInt64PrefixScan(t *testing.T) {
+	interfaceRegistry := types.NewInterfaceRegistry()
+	cdc := codec.NewProtoCodec(interfaceRegistry)
+
+	tb, err := NewAutoUInt64Table(AutoUInt64TablePrefix, AutoUInt64TableSeqPrefix, &testdata.TableModel{}, cdc)
+	require.NoError(t, err)
+
+	ctx := NewMockContext()
+	store := ctx.KVStore(sdk.NewKVStoreKey("test"))
+
+	metadata := []byte("metadata")
+	t1 := testdata.TableModel{
+		Id:       1,
+		Name:     "my test 1",
+		Metadata: metadata,
+	}
+	t2 := testdata.TableModel{
+		Id:       2,
+		Name:     "my test 2",
+		Metadata: metadata,
+	}
+	t3 := testdata.TableModel{
+		Id:       3,
+		Name:     "my test 3",
+		Metadata: metadata,
+	}
+	for _, g := range []testdata.TableModel{t1, t2, t3} {
+		_, err := tb.Create(store, &g)
+		require.NoError(t, err)
+	}
+
+	specs := map[string]struct {
+		start, end uint64
+		expResult  []testdata.TableModel
+		expRowIDs  []RowID
+		expError   *errors.Error
+		method     func(store sdk.KVStore, start uint64, end uint64) (Iterator, error)
+	}{
+		"first element": {
+			start:     1,
+			end:       2,
+			method:    tb.PrefixScan,
+			expResult: []testdata.TableModel{t1},
+			expRowIDs: []RowID{EncodeSequence(1)},
+		},
+		"first 2 elements": {
+			start:     1,
+			end:       3,
+			method:    tb.PrefixScan,
+			expResult: []testdata.TableModel{t1, t2},
+			expRowIDs: []RowID{EncodeSequence(1), EncodeSequence(2)},
+		},
+		"first 3 elements": {
+			start:     1,
+			end:       4,
+			method:    tb.PrefixScan,
+			expResult: []testdata.TableModel{t1, t2, t3},
+			expRowIDs: []RowID{EncodeSequence(1), EncodeSequence(2), EncodeSequence(3)},
+		},
+		"search with max end": {
+			start:     1,
+			end:       math.MaxUint64,
+			method:    tb.PrefixScan,
+			expResult: []testdata.TableModel{t1, t2, t3},
+			expRowIDs: []RowID{EncodeSequence(1), EncodeSequence(2), EncodeSequence(3)},
+		},
+		"2 to end": {
+			start:     2,
+			end:       5,
+			method:    tb.PrefixScan,
+			expResult: []testdata.TableModel{t2, t3},
+			expRowIDs: []RowID{EncodeSequence(2), EncodeSequence(3)},
+		},
+		"start before end should fail": {
+			start:    2,
+			end:      1,
+			method:   tb.PrefixScan,
+			expError: errors.ErrORMInvalidArgument,
+		},
+		"start equals end should fail": {
+			start:    1,
+			end:      1,
+			method:   tb.PrefixScan,
+			expError: errors.ErrORMInvalidArgument,
+		},
+		"reverse first element": {
+			start:     1,
+			end:       2,
+			method:    tb.ReversePrefixScan,
+			expResult: []testdata.TableModel{t1},
+			expRowIDs: []RowID{EncodeSequence(1)},
+		},
+		"reverse first 2 elements": {
+			start:     1,
+			end:       3,
+			method:    tb.ReversePrefixScan,
+			expResult: []testdata.TableModel{t2, t1},
+			expRowIDs: []RowID{EncodeSequence(2), EncodeSequence(1)},
+		},
+		"reverse first 3 elements": {
+			start:     1,
+			end:       4,
+			method:    tb.ReversePrefixScan,
+			expResult: []testdata.TableModel{t3, t2, t1},
+			expRowIDs: []RowID{EncodeSequence(3), EncodeSequence(2), EncodeSequence(1)},
+		},
+		"reverse search with max end": {
+			start:     1,
+			end:       math.MaxUint64,
+			method:    tb.ReversePrefixScan,
+			expResult: []testdata.TableModel{t3, t2, t1},
+			expRowIDs: []RowID{EncodeSequence(3), EncodeSequence(2), EncodeSequence(1)},
+		},
+		"reverse 2 to end": {
+			start:     2,
+			end:       5,
+			method:    tb.ReversePrefixScan,
+			expResult: []testdata.TableModel{t3, t2},
+			expRowIDs: []RowID{EncodeSequence(3), EncodeSequence(2)},
+		},
+		"reverse start before end should fail": {
+			start:    2,
+			end:      1,
+			method:   tb.ReversePrefixScan,
+			expError: errors.ErrORMInvalidArgument,
+		},
+		"reverse start equals end should fail": {
+			start:    1,
+			end:      1,
+			method:   tb.ReversePrefixScan,
+			expError: errors.ErrORMInvalidArgument,
+		},
+	}
+	for msg, spec := range specs {
+		t.Run(msg, func(t *testing.T) {
+			it, err := spec.method(store, spec.start, spec.end)
+			require.True(t, spec.expError.Is(err), "expected #+v but got #+v", spec.expError, err)
+			if spec.expError != nil {
+				return
+			}
+			var loaded []testdata.TableModel
+			rowIDs, err := ReadAll(it, &loaded)
+			require.NoError(t, err)
+			assert.Equal(t, spec.expResult, loaded)
+			assert.Equal(t, spec.expRowIDs, rowIDs)
+		})
+	}
+}

x/group/internal/orm/example_test.go

@@ -6,30 +6,61 @@ import (
 )
 
 type TestKeeper struct {
-	autoUInt64Table *AutoUInt64Table
-	primaryKeyTable *PrimaryKeyTable
+	autoUInt64Table                     *AutoUInt64Table
+	primaryKeyTable                     *PrimaryKeyTable
+	autoUInt64TableModelByMetadataIndex Index
+	primaryKeyTableModelByNameIndex     Index
+	primaryKeyTableModelByNumberIndex   Index
+	primaryKeyTableModelByMetadataIndex Index
 }
 
 var (
-	AutoUInt64TableTablePrefix [2]byte = [2]byte{0x0}
-	PrimaryKeyTablePrefix      [2]byte = [2]byte{0x1}
-	AutoUInt64TableSeqPrefix   byte    = 0x2
+	AutoUInt64TablePrefix                [2]byte = [2]byte{0x0}
+	PrimaryKeyTablePrefix                [2]byte = [2]byte{0x1}
+	AutoUInt64TableSeqPrefix             byte    = 0x2
+	AutoUInt64TableModelByMetadataPrefix byte    = 0x4
+	PrimaryKeyTableModelByNamePrefix     byte    = 0x5
+	PrimaryKeyTableModelByNumberPrefix   byte    = 0x6
+	PrimaryKeyTableModelByMetadataPrefix byte    = 0x7
 )
 
 func NewTestKeeper(cdc codec.Codec) TestKeeper {
 	k := TestKeeper{}
+	var err error
 
-	autoUInt64Table, err := NewAutoUInt64Table(AutoUInt64TableTablePrefix, AutoUInt64TableSeqPrefix, &testdata.TableModel{}, cdc)
+	k.autoUInt64Table, err = NewAutoUInt64Table(AutoUInt64TablePrefix, AutoUInt64TableSeqPrefix, &testdata.TableModel{}, cdc)
+	if err != nil {
+		panic(err.Error())
+	}
+	k.autoUInt64TableModelByMetadataIndex, err = NewIndex(k.autoUInt64Table, AutoUInt64TableModelByMetadataPrefix, func(val interface{}) ([]interface{}, error) {
+		return []interface{}{val.(*testdata.TableModel).Metadata}, nil
+	}, testdata.TableModel{}.Metadata)
 	if err != nil {
 		panic(err.Error())
 	}
-	k.autoUInt64Table = autoUInt64Table
 
-	primaryKeyTable, err := NewPrimaryKeyTable(PrimaryKeyTablePrefix, &testdata.TableModel{}, cdc)
+	k.primaryKeyTable, err = NewPrimaryKeyTable(PrimaryKeyTablePrefix, &testdata.TableModel{}, cdc)
+	if err != nil {
+		panic(err.Error())
+	}
+	k.primaryKeyTableModelByNameIndex, err = NewIndex(k.primaryKeyTable, PrimaryKeyTableModelByNamePrefix, func(val interface{}) ([]interface{}, error) {
+		return []interface{}{val.(*testdata.TableModel).Name}, nil
+	}, testdata.TableModel{}.Name)
+	if err != nil {
+		panic(err.Error())
+	}
+	k.primaryKeyTableModelByNumberIndex, err = NewIndex(k.primaryKeyTable, PrimaryKeyTableModelByNumberPrefix, func(val interface{}) ([]interface{}, error) {
+		return []interface{}{val.(*testdata.TableModel).Number}, nil
+	}, testdata.TableModel{}.Number)
+	if err != nil {
+		panic(err.Error())
+	}
+	k.primaryKeyTableModelByMetadataIndex, err = NewIndex(k.primaryKeyTable, PrimaryKeyTableModelByMetadataPrefix, func(val interface{}) ([]interface{}, error) {
+		return []interface{}{val.(*testdata.TableModel).Metadata}, nil
+	}, testdata.TableModel{}.Metadata)
 	if err != nil {
 		panic(err.Error())
 	}
-	k.primaryKeyTable = primaryKeyTable
 
 	return k
 }