Search Apps Documentation Source Content File Folder Download Copy Actions Download State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

v2 source pure

Package collection provides a generic collection implementation with support for multiple indexes, including unique i...

Readme View source

gno.land/p/moul/collection/v1

TODO: describe this package.


Part of moul/gno-contracts — moul's versioned gno.land contracts. See the repository for the full catalog, build/test tooling, and usage.

Dependency graph:

gno.land/p/moul/collection/v2 dependency graph

⚠️ Disclaimer: provided as-is, without warranty; not security-audited. Full disclaimer: DISCLAIMER.

Overview

Package collection provides a generic collection implementation with support for multiple indexes, including unique indexes and case-insensitive indexes. It is designed to be used with any type and allows efficient lookups using different fields or computed values.

Example usage:

Example
 1// Define a data type
 2type User struct {
 3    Name     string
 4    Email    string
 5    Age      int
 6    Username string
 7    Tags     []string
 8}
 9
10// Create a new collection
11c := collection.New()
12
13// Add indexes with different options
14c.AddIndex("name", func(v any) string {
15    return v.(*User).Name
16}, UniqueIndex)
17
18c.AddIndex("email", func(v any) string {
19    return v.(*User).Email
20}, UniqueIndex|CaseInsensitiveIndex)
21
22c.AddIndex("age", func(v any) string {
23    return strconv.Itoa(v.(*User).Age)
24}, DefaultIndex)  // Non-unique index
25
26c.AddIndex("username", func(v any) string {
27    return v.(*User).Username
28}, UniqueIndex|SparseIndex)  // Allow empty usernames
29
30// For tags, we index all tags for the user
31c.AddIndex("tag", func(v any) []string {
32    return v.(*User).Tags
33}, DefaultIndex)  // Non-unique to allow multiple users with same tag
34
35// Store an object
36id := c.Set(&User{
37    Name:  "Alice",
38    Email: "[email protected]",
39    Age:   30,
40    Tags:  []string{"admin", "moderator"},  // User can have multiple tags
41})
42
43// Retrieve by any index
44entry := c.GetFirst("email", "[email protected]")
45adminUsers := c.GetAll("tag", "admin")      // Find all users with admin tag
46modUsers := c.GetAll("tag", "moderator")    // Find all users with moderator tag

Index options can be combined using the bitwise OR operator. Available options:

  • DefaultIndex: Regular index with no special behavior
  • UniqueIndex: Ensures values are unique within the index
  • CaseInsensitiveIndex: Makes string comparisons case-insensitive
  • SparseIndex: Skips indexing empty values (nil or empty string)

Example: UniqueIndex|CaseInsensitiveIndex for a case-insensitive unique index

Constants 2

const IDIndex

1const (
2	// IDIndex is the reserved name for the primary key index
3	IDIndex = "_id"
4)
source

Functions 1

func New

1func New() *Collection
source

New creates a new Collection instance with an initialized ID index. The ID index is a special unique index that is always present and serves as the primary key for all objects in the collection.

Types 5

type Collection

struct
1type Collection struct {
2	indexes map[string]*Index
3	idGen   seqid.ID
4}
source

Collection represents a collection of objects with multiple indexes

Methods on Collection

func AddIndex

method on Collection
1func (c *Collection) AddIndex(name string, indexFn any, options IndexOption)
source

AddIndex adds a new index to the collection with the specified options

Parameters:

  • name: the unique name of the index (e.g., "tags")
  • indexFn: a function that extracts either a string or []string from an object
  • options: bit flags for index configuration (e.g., UniqueIndex)

func Delete

method on Collection
1func (c *Collection) Delete(id uint64) bool
source

Delete removes an object by its ID and returns true if something was deleted

func Get

method on Collection
1func (c *Collection) Get(indexName string, key string) EntryIterator
source

Get retrieves entries matching the given key in the specified index. Returns an iterator over the matching entries.

func GetAll

method on Collection
1func (c *Collection) GetAll(indexName string, key string) []Entry
source

GetAll retrieves all entries matching the given key in the specified index.

func GetFirst

method on Collection
1func (c *Collection) GetFirst(indexName, key string) *Entry
source

GetFirst returns the first matching entry or nil if none found

func GetIndex

method on Collection
1func (c *Collection) GetIndex(name string) avl.ITree
source

GetIndex returns the underlying tree for an index

func Set

method on Collection
1func (c *Collection) Set(obj any) uint64
source

Set adds or updates an object in the collection. Returns a positive ID if successful. Returns 0 if:

  • The object is nil
  • A uniqueness constraint would be violated
  • Index generation fails for any index

func Update

method on Collection
1func (c *Collection) Update(id uint64, obj any) bool
source

Update updates an existing object and returns true if successful Returns true if the update was successful. Returns false if:

  • The object is nil
  • The ID doesn't exist
  • A uniqueness constraint would be violated
  • Index generation fails for any index

If the update fails, the collection remains unchanged.

type Entry

struct
1type Entry struct {
2	ID  string
3	Obj any
4}
source

Entry represents a single object in the collection with its ID

Methods on Entry

func String

method on Entry
1func (e *Entry) String() string
source

String returns a string representation of the Entry

type EntryIterator

struct
 1type EntryIterator struct {
 2	collection *Collection
 3	indexName  string
 4	key        string
 5	currentID  string
 6	currentObj any
 7	err        error
 8	closed     bool
 9
10	// For multi-value cases
11	ids        []string
12	currentIdx int
13}
source

EntryIterator provides iteration over collection entries

Methods on EntryIterator

func Close

method on EntryIterator
1func (ei *EntryIterator) Close() error
source

func Empty

method on EntryIterator
1func (ei *EntryIterator) Empty() bool
source

func Error

method on EntryIterator
1func (ei *EntryIterator) Error() error
source

func Next

method on EntryIterator
1func (ei *EntryIterator) Next() bool
source

func Value

method on EntryIterator
1func (ei *EntryIterator) Value() *Entry
source

type Index

struct
1type Index struct {
2	fn      any
3	options IndexOption
4	tree    avl.ITree
5}
source

Index represents an index with its configuration and data. The index function can return either:

  • string: for single-value indexes
  • []string: for multi-value indexes where one object can be indexed under multiple keys

The backing tree stores either a single ID or []string for multiple IDs per key.

type IndexOption

ident
1type IndexOption uint64
source

IndexOption represents configuration options for an index using bit flags

Imports 5

Source Files 4