feat(client): add escape hatch for null slice & maps

Author: stainless-app[bot]

internal/encoding/json/encode.go

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

internal/encoding/json/sentinel/null.go

@@ -6,52 +6,41 @@ import (
 	"sync"
 )
 
-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))
+type cacheEntry struct {
+	x    any
+	ptr  uintptr
+	kind reflect.Kind
 }
 
-var nullSlicesCache sync.Map // map[reflect.Type][]T
+var nullCache sync.Map // map[reflect.Type]cacheEntry
 
-func NullSlice[T any]() []T {
+func NewNullSentinel[T any](mk func() T) T {
 	t := shims.TypeFor[T]()
-	slice, loaded := nullSlicesCache.Load(t) // avoid premature allocation
+	entry, loaded := nullCache.Load(t) // avoid premature allocation
 	if !loaded {
-		slice, _ = nullSlicesCache.LoadOrStore(t, []T{})
+		x := mk()
+		ptr := reflect.ValueOf(x).Pointer()
+		entry, _ = nullCache.LoadOrStore(t, cacheEntry{x, ptr, t.Kind()})
 	}
-	return slice.([]T)
+	return entry.(cacheEntry).x.(T)
 }
 
-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
+// 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
 	}
-	nullptr, ok := nullPtrsCache.Load(v.Type().Elem())
-	return ok && v.Pointer() == reflect.ValueOf(nullptr).Pointer()
+	return false
 }
 
-// internal only
-func IsValueNullSlice(v reflect.Value) bool {
-	if v.Kind() != reflect.Slice {
-		return false
+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
 	}
-	nullSlice, ok := nullSlicesCache.Load(v.Type().Elem())
-	return ok && v.Pointer() == reflect.ValueOf(nullSlice).Pointer()
+	return false
 }

internal/encoding/json/sentinel/sentinel_test.go

@@ -2,6 +2,7 @@ package sentinel_test
 
 import (
 	"github.com/openai/openai-go/internal/encoding/json/sentinel"
+	"github.com/openai/openai-go/packages/param"
 	"reflect"
 	"slices"
 	"testing"
@@ -15,25 +16,19 @@ type Pair struct {
 func TestNullSlice(t *testing.T) {
 	var nilSlice []int = nil
 	var nonNilSlice []int = []int{1, 2, 3}
-	var nullSlice []int = sentinel.NullSlice[int]()
+	var nullSlice []int = param.NullSlice[[]int]()
 
 	cases := map[string]Pair{
-		"nilSlice":            {sentinel.IsNullSlice(nilSlice), false},
-		"nullSlice":           {sentinel.IsNullSlice(nullSlice), true},
-		"newNullSlice":        {sentinel.IsNullSlice(sentinel.NullSlice[int]()), true},
+		"nilSlice":            {sentinel.IsNull(nilSlice), false},
+		"nullSlice":           {sentinel.IsNull(nullSlice), true},
+		"newNullSlice":        {sentinel.IsNull(param.NullSlice[[]int]()), true},
 		"lenNullSlice":        {len(nullSlice) == 0, true},
-		"nilSliceValue":       {sentinel.IsValueNullSlice(reflect.ValueOf(nilSlice)), false},
-		"nullSliceValue":      {sentinel.IsValueNullSlice(reflect.ValueOf(nullSlice)), true},
+		"nilSliceValue":       {sentinel.IsValueNull(reflect.ValueOf(nilSlice)), false},
+		"nullSliceValue":      {sentinel.IsValueNull(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
@@ -44,37 +39,20 @@ func TestNullSlice(t *testing.T) {
 	}
 }
 
-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")
-	}
+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]()
 
 	cases := map[string]Pair{
-		"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},
+		"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},
 	}
 
 	for name, test := range cases {
@@ -86,3 +64,28 @@ func TestNullPtr(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/paramutil/sentinel.go

@@ -0,0 +1,19 @@
+package param
+
+import "github.com/openai/openai-go/internal/encoding/json/sentinel"
+
+// NullMap returns a non-nil map with a length of 0.
+// When used with [MarshalObject] or [MarshalUnion], it will be marshaled as null.
+//
+// It is unspecified behavior to mutate the slice returned by [NullSlice].
+func NullMap[MapT ~map[string]T, T any]() MapT {
+	return sentinel.NewNullSentinel(func() MapT { return make(MapT, 1) })
+}
+
+// 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 unspecified behavior to mutate the slice returned by [NullSlice].
+func NullSlice[SliceT ~[]T, T any]() SliceT {
+	return sentinel.NewNullSentinel(func() SliceT { return make(SliceT, 0, 1) })
+}

packages/param/null.go

@@ -0,0 +1,49 @@
+package param_test
+
+import (
+	"encoding/json"
+	"github.com/openai/openai-go/packages/param"
+	"testing"
+)
+
+type Nullables struct {
+	Slice []int          `json:"slice,omitzero"`
+	Map   map[string]int `json:"map,omitzero"`
+	param.APIObject
+}
+
+func (n Nullables) MarshalJSON() ([]byte, error) {
+	type shadow Nullables
+	return param.MarshalObject(n, (*shadow)(&n))
+}
+
+func TestNullMarshal(t *testing.T) {
+	bytes, err := json.Marshal(Nullables{})
+	if err != nil {
+		t.Fatalf("json error %v", err.Error())
+	}
+	if string(bytes) != `{}` {
+		t.Fatalf("expected empty object, got %s", string(bytes))
+	}
+
+	obj := Nullables{
+		Slice: param.NullSlice[[]int](),
+		Map:   param.NullMap[map[string]int](),
+	}
+	bytes, err = json.Marshal(obj)
+
+	if !param.IsNull(obj.Slice) {
+		t.Fatal("failed null check")
+	}
+	if !param.IsNull(obj.Map) {
+		t.Fatal("failed null check")
+	}
+
+	if err != nil {
+		t.Fatalf("json error %v", err.Error())
+	}
+	exp := `{"slice":null,"map":null}`
+	if string(bytes) != exp {
+		t.Fatalf("expected %s, got %s", exp, string(bytes))
+	}
+}

packages/param/null_test.go

@@ -2,6 +2,7 @@ package param
 
 import (
 	"encoding/json"
+	"github.com/openai/openai-go/internal/encoding/json/sentinel"
 	"reflect"
 )
 
@@ -58,12 +59,21 @@ 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] or [Null]
+// To set a param to null use [NullStruct], [Null], [NullMap], or [NullSlice]
 // depending on the type of v.
 //
 // IsNull returns false if the value is omitted.
-func IsNull(v ParamNullable) bool {
-	return v.null()
+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
 }
 
 // ParamNullable encapsulates all structs in parameters,