From 92197e9b0ebebe0816effd1de16f8aed3d68fbce Mon Sep 17 00:00:00 2001
From: nobypass <nobypass.yt@gmail.com>
Date: Wed, 16 Oct 2024 11:17:16 +0200
Subject: [PATCH] some small adjustments + improve docs

---
 README.md        | 45 ++++++++++++++++++++++++++++++++++++++++++++-
 query.go         |  4 ++--
 rpc/internal.go  |  2 +-
 rpc/websocket.go |  2 +-
 surgo.go         |  1 +
 5 files changed, 49 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 2cbc7c3..10e3857 100644
--- a/README.md
+++ b/README.md
@@ -144,6 +144,38 @@ Unmarshal and Scan functions will automatically convert the SurrealDB formats ba
 If you don't like using the `db` tag, or your struct already uses it for something else, you can use the `fallback` tag.
 For example if most of your structs use the `json` tag, you can set the fallback tag to `json`. This way for the fields
 which don't have a `db` tag, the library will look for a `json` tag. Here is an example:
+````go
+type User struct {
+	// `dbName` will be used for marshaling since the db tag takes priority over the fallback tag
+    Name string `json:"name,omitempty" db:"dbName"`
+	// `birthday` will be used for marshaling since no db tag was provided
+    Birthday time.Time `json:"birthday"`
+}
+
+db, err := surgo.Connect("ws://localhost:8000", &surgo.Credentials{
+    // enter your credentials here
+}, surgo.WithFallbackTag("json"))
+if err != nil {
+    // handle error
+}
+
+err := db.Query("CREATE $john CONTENT $data", map[string]any{
+    "john": "users:john",
+    "data": User{
+        Name: "John",
+        Birthday: time.Date(1980, 1, 1, 0, 0, 0, 0, time.UTC),
+    },
+}).Error
+````
+
+Running this will result in this entry in SurrealDB:
+```
+{
+    id: 'someRandomString',
+    dbName: 'John',
+    birthday: '1980-01-01T00:00:00Z'
+}
+```
 
 ### Tracing & Context
 You can use the `WithLogger` option to pass a custom logger/tracer to the `Connect` function. The logger/tracer must 
@@ -170,4 +202,15 @@ result := db.WithContext(ctx).Query("SELECT * FROM ONLY $john", map[string]any{
 })
 ```
 
-Of course, you can also use a cancelable context or timeout context.
+Of course, you can also use a cancelable context or timeout context.\
+These are the possible traces (They will be called in the order they are listed):
+
+| TraceType | Description                                                                                                                                                                               |
+| --- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| TraceQuery | This signals the start of a query and the data will be the query `string`                                                                                                                 |
+| TraceVars | At this point all vars were computed and the data will be a `map[string]any`                                                                                                              |
+| TraceResponse | This signals that SurrealDB responded and the data it responded with will be a `map[string]any`                                                                                           |
+| TraceEnd | This signals the end of the query and the data will be the value which the called function returned * |
+
+\* This will be either of type `*surgo.Result` for a `DB.Query` call or simply `error` for a `DB.Scan` call.\
+If an error occurs between steps, these traces will be skipped and `TraceEnd` will be called immediately.
diff --git a/query.go b/query.go
index 126ad15..ad1a810 100644
--- a/query.go
+++ b/query.go
@@ -53,10 +53,10 @@ func (db *DB) Query(query string, vars map[string]any) (result *Result) {
 // If multiple results are expected, a pointer to a slice of structs or maps can be passed.
 // NOTE: Only the last result (the last query if multiple are present) is scanned into the
 // given object. If any of the queries fail, the error is returned.
-func (db DB) Scan(dest any, query string, vars map[string]any) error {
+func (db DB) Scan(dest any, query string, vars map[string]any) (err error) {
 	db.ctx = context.WithValue(safeContext(db.ctx), scanCtxKey, true)
 	defer func() {
-		db.logger.Trace(db.ctx, TraceEnd, nil)
+		db.logger.Trace(db.ctx, TraceEnd, err)
 	}()
 
 	result := db.Query(query, vars)
diff --git a/rpc/internal.go b/rpc/internal.go
index 8eb7d1b..b78bb3e 100644
--- a/rpc/internal.go
+++ b/rpc/internal.go
@@ -10,7 +10,7 @@ import (
 
 func (c *WebsocketConn) listen() {
 	for {
-		_, msg, err := c.Read(context.TODO())
+		_, msg, err := c.Read(context.Background())
 		if err != nil {
 			c.logger.Error(err)
 			return
diff --git a/rpc/websocket.go b/rpc/websocket.go
index 8bd0698..9830ffe 100644
--- a/rpc/websocket.go
+++ b/rpc/websocket.go
@@ -18,7 +18,7 @@ type Logger interface {
 }
 
 func NewWebsocketConn(url string, logger Logger) (*WebsocketConn, error) {
-	c, _, err := websocket.Dial(context.TODO(), url, nil)
+	c, _, err := websocket.Dial(context.Background(), url, nil)
 	if err != nil {
 		return nil, err
 	}
diff --git a/surgo.go b/surgo.go
index 26574d5..5106621 100644
--- a/surgo.go
+++ b/surgo.go
@@ -49,6 +49,7 @@ func Connect(url string, creds *Credentials, opts ...Option) (*DB, error) {
 
 	ctx, cancel := context.WithTimeout(context.Background(), db.timeout)
 	defer cancel()
+
 	_, err = c.Send(ctx, "signin", []any{creds})
 	if err != nil {
 		return nil, errs.ErrInvalidCredentials.With(err)