improved go doc on all packages

Author: dstpierre

README.md

@@ -39,15 +39,99 @@ vendor lock-in, and your data stays in your control.
 
 ## Import as Go package
 
-As of v1.4.1 StaticBackend offer an importable Go package removing the need 
+As of v1.4.1 StaticBackend offers an importable Go package removing the need 
 to self-host the backend API while keeping all functionalities from your Go 
 program.
 
 ### Example usage
 
 ```go
+package main
+
+import (
+	"fmt"
+	"log"
+	"time"
+
+	"github.com/staticbackendhq/core/backend"
+	"github.com/staticbackendhq/core/config"
+	"github.com/staticbackendhq/core/model"
+)
+
+type Task struct {
+	ID        string `json:"id"`
+	AccountID string `json:"accountId"`
+	Title     string `json:"title"`
+	Done      bool   `json:"done"`
+}
+
+func main() {
+	cfg := config.AppConfig{
+		AppEnv: "dev",
+		Port:   "8099",
+		DatabaseURL:     "mem",
+		DataStore:       "mem",
+		LocalStorageURL: "http://localhost:8099",
+	}
+	// this initialized the backend from config
+	backend.Setup(cfg)
+
+	// You can access most of the raw building blocks directly from the 
+	// package exported variables (which are interface) initialized via the 
+	// config you pass
+
+	// Set a value in the cache
+	backend.Cache.Set("key", "value")
+
+	// For strongly-typed database functionalities
+
+	// in a real app you'd have a middleware handling identifying and fetching a 
+	// model.DatabaseConfig for the current request. For this README sample 
+	// we're faking a real call which would fail if ran.
+	base, _ := backend.DB.FindDatabase("current-web-request-db-id")
+
+	// let's create a user in this new Database
+	usr := backend.Membership(base)
+	sessionToken, user, err := usr.CreateAccountAndUser("[email protected]", "passwd123456", 100)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// we simulate having authenticating this user (from middleware normally)
+	// in a real app you'd store the sessionToken in your user's 
+	// app (cookie, local storage, etc)
+	// You'd need to have a middleware responsible of validating this token 
+	// and have a model.Auth for the rest of your pipeline.
+	auth := model.Auth{
+		AccountID: user.AccountID,
+		UserID:    user.ID,
+		Email:     user.Email,
+		Role:      user.Role,
+		Token:     user.Token,
+	}
 
+	// we create a strongly-typed instance of the "tasks" collection
+	// so we have full CRUD / Queries functions for your Task type
+	tasks := backend.Collection[Task](auth, base, "tasks")
+
+	newTask := Task{Title: "my task", Done: false}
+
+	newTask, err = tasks.Create(newTask)
+	if err != nil {
+		log.Fatal(err)
+	}
+}
 ```
+
+### Documentation for the `backend` Go package
+
+Refer to the 
+[Go documentation](https://pkg.go.dev/github.com/staticbackendhq/core/backend) 
+to know about all functions and examples.
+
+
+
+
 ## What can you build
 
 I built StaticBackend with the mindset of someone tired of writing the same code 

backend/backend.go

@@ -56,7 +56,6 @@ import (
 	"github.com/staticbackendhq/core/email"
 	"github.com/staticbackendhq/core/function"
 	"github.com/staticbackendhq/core/logger"
-	"github.com/staticbackendhq/core/middleware"
 	"github.com/staticbackendhq/core/model"
 	"github.com/staticbackendhq/core/storage"
 	mongodrv "go.mongodb.org/mongo-driver/mongo"
@@ -208,23 +207,3 @@ func openPGDatabase(dbHost string) (*sql.DB, error) {
 
 	return dbConn, nil
 }
-
-func findAuthz(token string) model.Auth {
-	auth, err := middleware.ValidateAuthKey(DB, Cache, context.Background(), token)
-	if err != nil {
-		return model.Auth{}
-	}
-	return auth
-}
-
-func findBasez(baseID string) model.DatabaseConfig {
-	var conf model.DatabaseConfig
-	if err := Cache.GetTyped(baseID, &conf); err != nil {
-		db, err := DB.FindDatabase(baseID)
-		if err != nil {
-			return conf
-		}
-		conf = db
-	}
-	return conf
-}

backend/database.go

@@ -11,24 +11,26 @@ import (
 type Database[T any] struct {
 	auth model.Auth
 	conf model.DatabaseConfig
+	col  string
 }
 
 // Collection returns a ready to use Database to perform operations on a specific type
-func Collection[T any](auth model.Auth, base model.DatabaseConfig) Database[T] {
+func Collection[T any](auth model.Auth, base model.DatabaseConfig, col string) Database[T] {
 	return Database[T]{
 		auth: auth,
 		conf: base,
+		col:  col,
 	}
 }
 
 // Create creates a record in the collection/repository
-func (d Database[T]) Create(col string, data T) (inserted T, err error) {
+func (d Database[T]) Create(data T) (inserted T, err error) {
 	doc, err := toDoc(data)
 	if err != nil {
 		return
 	}
 
-	doc, err = DB.CreateDocument(d.auth, d.conf.Name, col, doc)
+	doc, err = DB.CreateDocument(d.auth, d.conf.Name, d.col, doc)
 	if err != nil {
 		return
 	}
@@ -37,7 +39,7 @@ func (d Database[T]) Create(col string, data T) (inserted T, err error) {
 }
 
 // BulkCreate creates multiple records in the collection/repository
-func (d Database[T]) BulkCreate(col string, entities []T) error {
+func (d Database[T]) BulkCreate(entities []T) error {
 	docs := make([]interface{}, 0)
 
 	for _, doc := range entities {
@@ -48,7 +50,7 @@ func (d Database[T]) BulkCreate(col string, entities []T) error {
 
 		docs = append(docs, x)
 	}
-	return DB.BulkCreateDocument(d.auth, d.conf.Name, col, docs)
+	return DB.BulkCreateDocument(d.auth, d.conf.Name, d.col, docs)
 }
 
 // PageResult wraps a slice of type T with paging information
@@ -60,8 +62,8 @@ type PagedResult[T any] struct {
 }
 
 // List returns records from a collection/repository using paging/sorting params
-func (d Database[T]) List(col string, lp model.ListParams) (res PagedResult[T], err error) {
-	r, err := DB.ListDocuments(d.auth, d.conf.Name, col, lp)
+func (d Database[T]) List(lp model.ListParams) (res PagedResult[T], err error) {
+	r, err := DB.ListDocuments(d.auth, d.conf.Name, d.col, lp)
 	if err != nil {
 		return
 	}
@@ -83,13 +85,13 @@ func (d Database[T]) List(col string, lp model.ListParams) (res PagedResult[T],
 }
 
 // Query returns records that match with the provided filters.
-func (d Database[T]) Query(col string, filters [][]any, lp model.ListParams) (res PagedResult[T], err error) {
+func (d Database[T]) Query(filters [][]any, lp model.ListParams) (res PagedResult[T], err error) {
 	clauses, err := DB.ParseQuery(filters)
 	if err != nil {
 		return
 	}
 
-	r, err := DB.QueryDocuments(d.auth, d.conf.Name, col, clauses, lp)
+	r, err := DB.QueryDocuments(d.auth, d.conf.Name, d.col, clauses, lp)
 	if err != nil {
 		return
 	}
@@ -111,8 +113,8 @@ func (d Database[T]) Query(col string, filters [][]any, lp model.ListParams) (re
 }
 
 // GetByID returns a specific record from a collection/repository
-func (d Database[T]) GetByID(col, id string) (entity T, err error) {
-	doc, err := DB.GetDocumentByID(d.auth, d.conf.Name, col, id)
+func (d Database[T]) GetByID(id string) (entity T, err error) {
+	doc, err := DB.GetDocumentByID(d.auth, d.conf.Name, d.col, id)
 	if err != nil {
 		return
 	}
@@ -122,13 +124,13 @@ func (d Database[T]) GetByID(col, id string) (entity T, err error) {
 }
 
 // Update updates some fields of a record
-func (d Database[T]) Update(col, id string, v any) (entity T, err error) {
+func (d Database[T]) Update(id string, v any) (entity T, err error) {
 	doc, err := toDoc(v)
 	if err != nil {
 		return
 	}
 
-	x, err := DB.UpdateDocument(d.auth, d.conf.Name, col, id, doc)
+	x, err := DB.UpdateDocument(d.auth, d.conf.Name, d.col, id, doc)
 	if err != nil {
 		return
 	}
@@ -138,7 +140,7 @@ func (d Database[T]) Update(col, id string, v any) (entity T, err error) {
 }
 
 // UpdateMany updates multiple records matching filters
-func (d Database[T]) UpdateMany(col string, filters [][]any, v any) (int64, error) {
+func (d Database[T]) UpdateMany(filters [][]any, v any) (int64, error) {
 	clauses, err := DB.ParseQuery(filters)
 	if err != nil {
 		return 0, err
@@ -148,17 +150,17 @@ func (d Database[T]) UpdateMany(col string, filters [][]any, v any) (int64, erro
 	if err != nil {
 		return 0, err
 	}
-	return DB.UpdateDocuments(d.auth, d.conf.Name, col, clauses, doc)
+	return DB.UpdateDocuments(d.auth, d.conf.Name, d.col, clauses, doc)
 }
 
 // IncrementValue increments or decrements a specifc field from a collection/repository
-func (d Database[T]) IncrementValue(col, id, field string, n int) error {
-	return DB.IncrementValue(d.auth, d.conf.Name, col, id, field, n)
+func (d Database[T]) IncrementValue(id, field string, n int) error {
+	return DB.IncrementValue(d.auth, d.conf.Name, d.col, id, field, n)
 }
 
 // Delete removes a record from a collection
-func (d Database[T]) Delete(col, id string) (int64, error) {
-	return DB.DeleteDocument(d.auth, d.conf.Name, col, id)
+func (d Database[T]) Delete(id string) (int64, error) {
+	return DB.DeleteDocument(d.auth, d.conf.Name, d.col, id)
 }
 
 func toDoc(v any) (doc map[string]any, err error) {

backend/database_test.go

@@ -32,17 +32,17 @@ func newTask(title string, done bool) Task {
 }
 
 func TestDatabaseCreate(t *testing.T) {
-	db := backend.Collection[Task](adminAuth, base)
+	db := backend.Collection[Task](adminAuth, base, "tasks")
 
 	task := newTask("db create", false)
-	task, err := db.Create("tasks", task)
+	task, err := db.Create(task)
 	if err != nil {
 		t.Fatal(err)
 	} else if len(task.ID) == 0 {
 		t.Error("expected task id length to be > 0")
 	}
 
-	check, err := db.GetByID("tasks", task.ID)
+	check, err := db.GetByID(task.ID)
 	if err != nil {
 		t.Fatal(err)
 	} else if task.Title != check.Title {
@@ -51,19 +51,19 @@ func TestDatabaseCreate(t *testing.T) {
 }
 
 func TestDatabaseList(t *testing.T) {
-	db := backend.Collection[Task](adminAuth, base)
+	db := backend.Collection[Task](adminAuth, base, "tasks")
 
 	tasks := []Task{
 		newTask("t1", false),
 		newTask("t2", true),
 	}
 
-	if err := db.BulkCreate("tasks", tasks); err != nil {
+	if err := db.BulkCreate(tasks); err != nil {
 		t.Fatal(err)
 	}
 
 	lp := model.ListParams{Page: 1, Size: 50}
-	res, err := db.List("tasks", lp)
+	res, err := db.List(lp)
 	if err != nil {
 		t.Fatal(err)
 	} else if len(res.Results) < 2 {
@@ -72,15 +72,15 @@ func TestDatabaseList(t *testing.T) {
 }
 
 func TestDatabaseQuery(t *testing.T) {
-	db := backend.Collection[Task](adminAuth, base)
+	db := backend.Collection[Task](adminAuth, base, "tasks")
 
 	tasks := []Task{
 		newTask("qry1", false),
 		newTask("qry2", true),
 		newTask("qry2", false),
 	}
 
-	if err := db.BulkCreate("tasks", tasks); err != nil {
+	if err := db.BulkCreate(tasks); err != nil {
 		t.Fatal(err)
 	}
 
@@ -93,7 +93,7 @@ func TestDatabaseQuery(t *testing.T) {
 	}
 
 	lp := model.ListParams{Page: 1, Size: 50}
-	res, err := db.Query("tasks", filters, lp)
+	res, err := db.Query(filters, lp)
 	if err != nil {
 		t.Fatal(err)
 	} else if res.Total != 1 {