doc.gno

 1// Package datastore provides support to store multiple collections of records.
 2//
 3// It supports the definition of multiple storages, where each one is a collection
 4// of records. Records can have any number of user defined fields which are added
 5// dynamically when values are set on a record. These fields can also be renamed
 6// or removed.
 7//
 8// Storages have support for simple schemas that allows users to pre-define fields
 9// which can optionally have a default value also defined. Default values are
10// assigned to new records on creation.
11//
12// User defined schemas can optionally be strict, which means that records from a
13// storage using the schema can only assign values to the pre-defined set of fields.
14// In which case, assigning a value to an unknown field would result on an error.
15//
16// Package also support the definition of custom record indexes. Indexes are used
17// by storages to search and iterate records.
18// The default index is the ID index but custom single and multi value indexes can
19// be defined.
20//
21// WARNING: Using this package to store your realm data must be carefully considered.
22// The fact that record fields are not strictly typed and can be renamed or removed
23// could lead to issues if not careful when coding your realm(s). So it's recommended
24// that you consider other alternatives first, like alternative patterns or solutions
25// provided by the blockchain to deal with data, types and data migration for example.
26//
27// Example usage:
28//
29//	var db datastore.Datastore
30//
31//	// Define a unique case insensitive index for user emails
32//	emailIdx := datastore.NewIndex("email", func(r datastore.Record) string {
33//	  return r.MustGet("email").(string)
34//	}).Unique().CaseInsensitive()
35//
36//	// Create a new storage for user records
37//	storage := db.CreateStorage("users", datastore.WithIndex(emailIdx))
38//
39//	// Add a user with a single "email" field
40//	user := storage.NewRecord()
41//	user.Set("email", "foo@bar.org")
42//
43//	// Save to assing user ID and update indexes
44//	user.Save()
45//
46//	// Find user by email using the custom index
47//	user, _ = storage.Get(emailIdx.Name(), "foo@bar.org")
48//
49//	// Find user by ID
50//	user, _ = storage.GetByID(user.ID())
51//
52//	// Search user's profile by email in another existing storage
53//	storage = db.GetStorage("profiles")
54//	email := user.MustGet("email").(string)
55//	profile, found := storage.Get("user", email)
56//	if !found {
57//	  panic("profile not found")
58//	}
59//
60//	// Delete the profile from the storage and update indexes
61//	storage.Delete(profile.ID())
62//
63// Example query usage:
64//
65//	var db datastore.Datastore
66//
67//	// Create a query with a custom offset and size
68//	storage := db.GetStorage("users")
69//	recordset, err := storage.Query(datastore.WithOffset(100), datastore.WithSize(50))
70//	if err != nil {
71//	  panic(err)
72//	}
73//
74//	// Get all query results
75//	var records []Record
76//	recordset.Iterate(func(r datastore.Record) bool {
77//	  records = append(records, r)
78//	  return false
79//	})
80//
81// Example query using a custom index usage:
82//
83//	var db datastore.Datastore
84//
85//	// Create a query to get records using a custom pre-defined index
86//	storage := db.GetStorage("posts")
87//	recordset, err := storage.Query(datastore.UseIndex("tags", "tagname"))
88//	if err != nil {
89//	  panic(err)
90//	}
91//
92//	// Get all query results
93//	var records []Record
94//	recordset.Iterate(func(r datastore.Record) bool {
95//	  records = append(records, r)
96//	  return false
97//	})
98package datastore