soft-deprecated Record.GetUploadedFiles in favour of Record.GetUnsavedFiles

CHANGELOG.md

@@ -14,6 +14,9 @@
 
 - Added JSVM `new Timezone(name)` binding for constructing `time.Location` value ([#6219](https://github.com/pocketbase/pocketbase/discussions/6219)).
 
+- Soft-deprecated `Record.GetUploadedFiles` in favour of `Record.GetUnsavedFiles` to minimize the ambiguities what the method do ([#6269](https://github.com/pocketbase/pocketbase/discussions/6269)).
+    (@todo update docs to reflect the `:unsaved` getter change)
+
 
 ## v0.24.2
 

core/field_file.go

@@ -5,6 +5,7 @@ import (
 	"database/sql/driver"
 	"errors"
 	"fmt"
+	"log"
 	"regexp"
 	"strings"
 
@@ -637,7 +638,13 @@ func (f *FileField) FindGetter(key string) GetterFunc {
 		return func(record *Record) any {
 			return record.GetRaw(f.Name)
 		}
+	case f.Name + ":unsaved":
+		return func(record *Record) any {
+			return f.extractUploadableFiles(f.toSliceValue(record.GetRaw(f.Name)))
+		}
 	case f.Name + ":uploaded":
+		// deprecated
+		log.Println("[file field getter] please replace :uploaded with :unsaved")
 		return func(record *Record) any {
 			return f.extractUploadableFiles(f.toSliceValue(record.GetRaw(f.Name)))
 		}

core/field_file_test.go

@@ -672,8 +672,8 @@ func TestFileFieldFindGetter(t *testing.T) {
 			`["300_UhLKX91HVb.png",{"name":"f1","originalName":"f1","size":4},{"name":"f2","originalName":"f2","size":4}]`,
 		},
 		{
-			"uploaded",
-			field.GetName() + ":uploaded",
+			"unsaved",
+			field.GetName() + ":unsaved",
 			true,
 			`[{"name":"f1","originalName":"f1","size":4},{"name":"f2","originalName":"f2","size":4}]`,
 		},

core/record_model.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"log"
 	"maps"
 	"slices"
 	"sort"
@@ -973,20 +974,20 @@ func (m *Record) GetStringSlice(key string) []string {
 	return list.ToUniqueStringSlice(m.Get(key))
 }
 
-// GetUploadedFiles returns the uploaded files for the provided "file" field key,
+// GetUnsavedFiles returns the uploaded files for the provided "file" field key,
 // (aka. the current [*filesytem.File] values) so that you can apply further
 // validations or modifications (including changing the file name or content before persisting).
 //
 // Example:
 //
-//	files := record.GetUploadedFiles("documents")
+//	files := record.GetUnsavedFiles("documents")
 //	for _, f := range files {
 //	    f.Name = "doc_" + f.Name // add a prefix to each file name
 //	}
 //	app.Save(record) // the files are pointers so the applied changes will transparently reflect on the record value
-func (m *Record) GetUploadedFiles(key string) []*filesystem.File {
-	if !strings.HasSuffix(key, ":uploaded") {
-		key += ":uploaded"
+func (m *Record) GetUnsavedFiles(key string) []*filesystem.File {
+	if !strings.HasSuffix(key, ":unsaved") {
+		key += ":unsaved"
 	}
 
 	values, _ := m.Get(key).([]*filesystem.File)
@@ -994,6 +995,12 @@ func (m *Record) GetUploadedFiles(key string) []*filesystem.File {
 	return values
 }
 
+// Deprecated: replaced with GetUnsavedFiles.
+func (m *Record) GetUploadedFiles(key string) []*filesystem.File {
+	log.Println("Please replace GetUploadedFiles with GetUnsavedFiles")
+	return m.GetUnsavedFiles(key)
+}
+
 // Retrieves the "key" json field value and unmarshals it into "result".
 //
 // Example

core/record_model_test.go

@@ -1013,7 +1013,7 @@ func TestRecordGetStringSlice(t *testing.T) {
 	}
 }
 
-func TestRecordGetUploadedFiles(t *testing.T) {
+func TestRecordGetUnsavedFiles(t *testing.T) {
 	t.Parallel()
 
 	app, _ := tests.NewTestApp()
@@ -1054,14 +1054,14 @@ func TestRecordGetUploadedFiles(t *testing.T) {
 			`[{"name":"f1","originalName":"f1","size":4},{"name":"f2","originalName":"f2","size":4}]`,
 		},
 		{
-			"files:uploaded",
+			"files:unsaved",
 			`[{"name":"f1","originalName":"f1","size":4},{"name":"f2","originalName":"f2","size":4}]`,
 		},
 	}
 
 	for i, s := range scenarios {
 		t.Run(fmt.Sprintf("%d_%#v", i, s.key), func(t *testing.T) {
-			v := record.GetUploadedFiles(s.key)
+			v := record.GetUnsavedFiles(s.key)
 
 			raw, err := json.Marshal(v)
 			if err != nil {