feat(api): api update

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 44
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gbox%2Fgbox-sdk-3b740aa1797fa0df593719056d00d7dc052b100b4d38593f1e9454c1be99be91.yml
-openapi_spec_hash: 1f3d27b14316ef4cc23fa6e926d61371
-config_hash: 6ecca2f2b1cb843a69ccd54e8c6179dc
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gbox%2Fgbox-sdk-9118b947ebe901fea6fe0bdb068f9d76b6cd1cb9dd4fd5e58cf53f716c59970f.yml
+openapi_spec_hash: d844099910f7699aaf0a6f1ba7a5df9f
+config_hash: e19ee82b9c29b95754a9f0c3d58e3034

api.md

@@ -776,7 +776,7 @@ type mapEncoder struct {
 }
 
 func (me mapEncoder) encode(e *encodeState, v reflect.Value, opts encOpts) {
-	if v.IsNil() /* EDIT(begin) */ || sentinel.IsValueNull(v) /* EDIT(end) */ {
+	if v.IsNil() {
 		e.WriteString("null")
 		return
 	}
@@ -855,7 +855,7 @@ type sliceEncoder struct {
 }
 
 func (se sliceEncoder) encode(e *encodeState, v reflect.Value, opts encOpts) {
-	if v.IsNil() /* EDIT(begin) */ || sentinel.IsValueNull(v) /* EDIT(end) */ {
+	if v.IsNil() {
 		e.WriteString("null")
 		return
 	}
@@ -916,7 +916,14 @@ type ptrEncoder struct {
 }
 
 func (pe ptrEncoder) encode(e *encodeState, v reflect.Value, opts encOpts) {
-	if v.IsNil() {
+	// EDIT(begin)
+	//
+	// if v.IsNil()  {
+	// 	e.WriteString("null")
+	// 	return
+	// }
+
+	if v.IsNil() || sentinel.IsValueNullPtr(v) || sentinel.IsValueNullSlice(v) {
 		e.WriteString("null")
 		return
 	}

internal/encoding/json/encode.go

@@ -6,41 +6,52 @@ import (
 	"sync"
 )
 
-type cacheEntry struct {
-	x    any
-	ptr  uintptr
-	kind reflect.Kind
+var nullPtrsCache sync.Map // map[reflect.Type]*T
+
+func NullPtr[T any]() *T {
+	t := shims.TypeFor[T]()
+	ptr, loaded := nullPtrsCache.Load(t) // avoid premature allocation
+	if !loaded {
+		ptr, _ = nullPtrsCache.LoadOrStore(t, new(T))
+	}
+	return (ptr.(*T))
 }
 
-var nullCache sync.Map // map[reflect.Type]cacheEntry
+var nullSlicesCache sync.Map // map[reflect.Type][]T
 
-func NewNullSentinel[T any](mk func() T) T {
+func NullSlice[T any]() []T {
 	t := shims.TypeFor[T]()
-	entry, loaded := nullCache.Load(t) // avoid premature allocation
+	slice, loaded := nullSlicesCache.Load(t) // avoid premature allocation
 	if !loaded {
-		x := mk()
-		ptr := reflect.ValueOf(x).Pointer()
-		entry, _ = nullCache.LoadOrStore(t, cacheEntry{x, ptr, t.Kind()})
+		slice, _ = nullSlicesCache.LoadOrStore(t, []T{})
 	}
-	return entry.(cacheEntry).x.(T)
+	return slice.([]T)
 }
 
-// for internal use only
-func IsValueNull(v reflect.Value) bool {
-	switch v.Kind() {
-	case reflect.Map, reflect.Slice:
-		null, ok := nullCache.Load(v.Type())
-		return ok && v.Pointer() == null.(cacheEntry).ptr
+func IsNullPtr[T any](ptr *T) bool {
+	nullptr, ok := nullPtrsCache.Load(shims.TypeFor[T]())
+	return ok && ptr == nullptr.(*T)
+}
+
+func IsNullSlice[T any](slice []T) bool {
+	nullSlice, ok := nullSlicesCache.Load(shims.TypeFor[T]())
+	return ok && reflect.ValueOf(slice).Pointer() == reflect.ValueOf(nullSlice).Pointer()
+}
+
+// internal only
+func IsValueNullPtr(v reflect.Value) bool {
+	if v.Kind() != reflect.Ptr {
+		return false
 	}
-	return false
+	nullptr, ok := nullPtrsCache.Load(v.Type().Elem())
+	return ok && v.Pointer() == reflect.ValueOf(nullptr).Pointer()
 }
 
-func IsNull[T any](v T) bool {
-	t := shims.TypeFor[T]()
-	switch t.Kind() {
-	case reflect.Map, reflect.Slice:
-		null, ok := nullCache.Load(t)
-		return ok && reflect.ValueOf(v).Pointer() == null.(cacheEntry).ptr
+// internal only
+func IsValueNullSlice(v reflect.Value) bool {
+	if v.Kind() != reflect.Slice {
+		return false
 	}
-	return false
+	nullSlice, ok := nullSlicesCache.Load(v.Type().Elem())
+	return ok && v.Pointer() == reflect.ValueOf(nullSlice).Pointer()
 }

internal/encoding/json/sentinel/null.go

@@ -2,7 +2,6 @@ package sentinel_test
 
 import (
 	"github.com/babelcloud/gbox-sdk-go/internal/encoding/json/sentinel"
-	"github.com/babelcloud/gbox-sdk-go/packages/param"
 	"reflect"
 	"slices"
 	"testing"
@@ -16,19 +15,25 @@ type Pair struct {
 func TestNullSlice(t *testing.T) {
 	var nilSlice []int = nil
 	var nonNilSlice []int = []int{1, 2, 3}
-	var nullSlice []int = param.NullSlice[[]int]()
+	var nullSlice []int = sentinel.NullSlice[int]()
 
 	cases := map[string]Pair{
-		"nilSlice":            {sentinel.IsNull(nilSlice), false},
-		"nullSlice":           {sentinel.IsNull(nullSlice), true},
-		"newNullSlice":        {sentinel.IsNull(param.NullSlice[[]int]()), true},
+		"nilSlice":            {sentinel.IsNullSlice(nilSlice), false},
+		"nullSlice":           {sentinel.IsNullSlice(nullSlice), true},
+		"newNullSlice":        {sentinel.IsNullSlice(sentinel.NullSlice[int]()), true},
 		"lenNullSlice":        {len(nullSlice) == 0, true},
-		"nilSliceValue":       {sentinel.IsValueNull(reflect.ValueOf(nilSlice)), false},
-		"nullSliceValue":      {sentinel.IsValueNull(reflect.ValueOf(nullSlice)), true},
+		"nilSliceValue":       {sentinel.IsValueNullSlice(reflect.ValueOf(nilSlice)), false},
+		"nullSliceValue":      {sentinel.IsValueNullSlice(reflect.ValueOf(nullSlice)), true},
 		"compareSlices":       {slices.Compare(nilSlice, nullSlice) == 0, true},
 		"compareNonNilSlices": {slices.Compare(nonNilSlice, nullSlice) == 0, false},
 	}
 
+	nilSlice = append(nullSlice, 12)
+	cases["append_result"] = Pair{sentinel.IsNullSlice(nilSlice), false}
+	cases["mutated_result"] = Pair{sentinel.IsNullSlice(nullSlice), true}
+	cases["append_result_len"] = Pair{len(nilSlice) == 1, true}
+	cases["append_null_slice_len"] = Pair{len(nullSlice) == 0, true}
+
 	for name, c := range cases {
 		t.Run(name, func(t *testing.T) {
 			got, want := c.got, c.want
@@ -39,20 +44,37 @@ func TestNullSlice(t *testing.T) {
 	}
 }
 
-func TestNullMap(t *testing.T) {
-	var nilMap map[string]int = nil
-	var nonNilMap map[string]int = map[string]int{"a": 1, "b": 2}
-	var nullMap map[string]int = param.NullMap[map[string]int]()
+func TestNullPtr(t *testing.T) {
+	var s *string = nil
+	var i *int = nil
+	var slice *[]int = nil
+
+	var nullptrStr *string = sentinel.NullPtr[string]()
+	var nullptrInt *int = sentinel.NullPtr[int]()
+	var nullptrSlice *[]int = sentinel.NullPtr[[]int]()
+
+	if *nullptrStr != "" {
+		t.Errorf("Failed to safely deref")
+	}
+	if *nullptrInt != 0 {
+		t.Errorf("Failed to safely deref")
+	}
+	if len(*nullptrSlice) != 0 {
+		t.Errorf("Failed to safely deref")
+	}
 
 	cases := map[string]Pair{
-		"nilMap":            {sentinel.IsNull(nilMap), false},
-		"nullMap":           {sentinel.IsNull(nullMap), true},
-		"newNullMap":        {sentinel.IsNull(param.NullMap[map[string]int]()), true},
-		"lenNullMap":        {len(nullMap) == 0, true},
-		"nilMapValue":       {sentinel.IsValueNull(reflect.ValueOf(nilMap)), false},
-		"nullMapValue":      {sentinel.IsValueNull(reflect.ValueOf(nullMap)), true},
-		"compareMaps":       {reflect.DeepEqual(nilMap, nullMap), false},
-		"compareNonNilMaps": {reflect.DeepEqual(nonNilMap, nullMap), false},
+		"nilStr":  {sentinel.IsNullPtr(s), false},
+		"nullStr": {sentinel.IsNullPtr(nullptrStr), true},
+
+		"nilInt":  {sentinel.IsNullPtr(i), false},
+		"nullInt": {sentinel.IsNullPtr(nullptrInt), true},
+
+		"nilSlice":  {sentinel.IsNullPtr(slice), false},
+		"nullSlice": {sentinel.IsNullPtr(nullptrSlice), true},
+
+		"nilValuePtr":  {sentinel.IsValueNullPtr(reflect.ValueOf(i)), false},
+		"nullValuePtr": {sentinel.IsValueNullPtr(reflect.ValueOf(nullptrInt)), true},
 	}
 
 	for name, test := range cases {
@@ -64,28 +86,3 @@ func TestNullMap(t *testing.T) {
 		})
 	}
 }
-
-func TestIsNullRepeated(t *testing.T) {
-	// Test for slices
-	nullSlice1 := param.NullSlice[[]int]()
-	nullSlice2 := param.NullSlice[[]int]()
-	if !sentinel.IsNull(nullSlice1) {
-		t.Errorf("IsNull(nullSlice1) = false, want true")
-	}
-	if !sentinel.IsNull(nullSlice2) {
-		t.Errorf("IsNull(nullSlice2) = false, want true")
-	}
-	if !sentinel.IsNull(nullSlice1) || !sentinel.IsNull(nullSlice2) {
-		t.Errorf("IsNull should return true for all NullSlice instances")
-	}
-
-	// Test for maps
-	nullMap1 := param.NullMap[map[string]int]()
-	nullMap2 := param.NullMap[map[string]int]()
-	if !sentinel.IsNull(nullMap1) {
-		t.Errorf("IsNull(nullMap1) = false, want true")
-	}
-	if !sentinel.IsNull(nullMap2) {
-		t.Errorf("IsNull(nullMap2) = false, want true")
-	}
-}

internal/encoding/json/sentinel/sentinel_test.go

@@ -0,0 +1,31 @@
+package paramutil
+
+import (
+	"github.com/babelcloud/gbox-sdk-go/internal/encoding/json/sentinel"
+)
+
+// NullPtr returns a pointer to the zero value of the type T.
+// When used with [MarshalObject] or [MarshalUnion], it will be marshaled as null.
+//
+// It is unspecified behavior to mutate the value pointed to by the returned pointer.
+func NullPtr[T any]() *T {
+	return sentinel.NullPtr[T]()
+}
+
+// IsNullPtr returns true if the pointer was created by [NullPtr].
+func IsNullPtr[T any](ptr *T) bool {
+	return sentinel.IsNullPtr(ptr)
+}
+
+// NullSlice returns a non-nil slice with a length of 0.
+// When used with [MarshalObject] or [MarshalUnion], it will be marshaled as null.
+//
+// It is undefined behavior to mutate the slice returned by [NullSlice].
+func NullSlice[T any]() []T {
+	return sentinel.NullSlice[T]()
+}
+
+// IsNullSlice returns true if the slice was created by [NullSlice].
+func IsNullSlice[T any](slice []T) bool {
+	return sentinel.IsNullSlice(slice)
+}

internal/paramutil/sentinel.go

@@ -2,7 +2,6 @@ package param
 
 import (
 	"encoding/json"
-	"github.com/babelcloud/gbox-sdk-go/internal/encoding/json/sentinel"
 	"reflect"
 )
 
@@ -59,21 +58,12 @@ func IsOmitted(v any) bool {
 
 // IsNull returns true if v was set to the JSON value null.
 //
-// To set a param to null use [NullStruct], [Null], [NullMap], or [NullSlice]
+// To set a param to null use [NullStruct] or [Null]
 // depending on the type of v.
 //
 // IsNull returns false if the value is omitted.
-func IsNull[T any](v T) bool {
-	if nullable, ok := any(v).(ParamNullable); ok {
-		return nullable.null()
-	}
-
-	switch reflect.TypeOf(v).Kind() {
-	case reflect.Slice, reflect.Map:
-		return sentinel.IsNull(v)
-	}
-
-	return false
+func IsNull(v ParamNullable) bool {
+	return v.null()
 }
 
 // ParamNullable encapsulates all structs in parameters,