spanenc

func ArrayValueFromSlice ¶

func ArrayValueFromSlice[T any](vs []T, opts ...EncodeOption) (spanner.GenericColumnValue, error)

ArrayValueFromSlice converts a homogeneous slice into an ARRAY spanner.GenericColumnValue with the element type inferred statically from T (see ValuesFromSlice for the homogeneity rules). Following the client library's slice handling, a nil slice becomes a typed NULL ARRAY and an empty slice an empty ARRAY.

func MutationColumnsAndValues ¶

func MutationColumnsAndValues(v any, opts ...ColumnMaskOption) ([]string, []any, error)

MutationColumnsAndValues extracts column names and plain Go field values from a struct (or non-nil pointer to struct), mirroring the client's structToMutationParams: read-only fields (`spanner:"->"` or `spanner:"Name;readonly"`, since spanner v1.86.0) are excluded from the results. The results fit the cols/vals form of mutation constructors such as spanner.Insert, spanner.Update, and spanner.Replace, so callers can mask columns by name before building the mutation — something the *Struct constructors cannot do.

Values are returned as-is (no GCV conversion); the client library encodes them when the mutation is applied, so this helper accepts whatever InsertStruct accepts. A nil pointer returns ErrNilStructPointer where the client would silently produce an empty mutation.

An update-mask-style column mask can be written as either an include list (WithColumns) or an exclude list (WithoutColumns); masked output keeps the struct declaration order, and mask mistakes (unknown columns, read-only columns in an include list, or combining both kinds) return ErrInvalidColumnMask.

package main

import (
	"fmt"

	"cloud.google.com/go/spanner"

	"github.com/apstndb/spanenc"
)

func main() {
	type Singer struct {
		SingerID  int64 `spanner:"SingerId"`
		FirstName string
		LastName  string
	}

	// Update only SingerId and LastName; the mask could equally be written
	// as an exclude list with WithoutColumns("FirstName").
	cols, vals, err := spanenc.MutationColumnsAndValues(
		Singer{SingerID: 1, FirstName: "Marc", LastName: "Richards"},
		spanenc.WithColumns("SingerId", "LastName"),
	)
	if err != nil {
		fmt.Println(err)
		return
	}
	_ = spanner.Update("Singers", cols, vals)
	fmt.Println(cols)
	fmt.Println(vals)
}

Output:
[SingerId LastName]
[1 Richards]

func MutationMap ¶

func MutationMap(v any, opts ...ColumnMaskOption) (map[string]any, error)

MutationMap extracts a column-name-to-Go-value map from a struct (or non-nil pointer to struct) for the *Map mutation constructors (spanner.InsertMap, spanner.UpdateMap, spanner.ReplaceMap, spanner.InsertOrUpdateMap). Read-only fields are excluded and the WithColumns / WithoutColumns masks apply, like MutationColumnsAndValues.

Duplicate column names (possible with explicit duplicate `spanner` tags) return an error rather than silently dropping a value.

func ParamsMap ¶ added in v0.3.0

func ParamsMap(v any, opts ...ColumnMaskOption) (map[string]any, error)

ParamsMap extracts a column-name-to-Go-value map from a struct (or non-nil pointer to struct) for binding as cloud.google.com/go/spanner.Statement Params (parameter names are the `spanner`-tagged column names). Values are returned as-is (no GCV conversion); the client library encodes them when the statement runs.

Unlike the write-shaped MutationMap, read-only fields are included — they are ordinary bindable values in a statement. The WithColumns / WithoutColumns masks apply, and an include mask may name read-only columns.

Duplicate column names (possible with explicit duplicate `spanner` tags) return an error rather than silently dropping a value.

func ResultSetMetadataFor ¶ added in v0.3.0

func ResultSetMetadataFor[T any]() (*sppb.ResultSetMetadata, error)

ResultSetMetadataFor wraps RowTypeFor into a sppb.ResultSetMetadata, the shape expected by result-set consumers such as github.com/apstndb/spanvalue/writer's WithMetadata. It suits client-side virtual result sets (status rows, SHOW-style outputs) whose rows are Go structs rather than server responses.

func ResultSetMetadataFromGoType ¶ added in v0.3.0

func ResultSetMetadataFromGoType(t reflect.Type) (*sppb.ResultSetMetadata, error)

ResultSetMetadataFromGoType is ResultSetMetadataFor for a reflect.Type.

func RowTypeFor ¶

func RowTypeFor[T any]() (*sppb.StructType, error)

RowTypeFor returns the sppb.StructType describing a row of T, pairing StructColumns names (read-only fields included) with statically inferred field types (see TypeFromGoType). It suits writer metadata such as github.com/apstndb/spanvalue/writer's WithRowType, or the row_type of a ResultSetMetadata.

Note that this row-shaped view flattens embedded struct fields, while a STRUCT-typed value of T (TypeFor, ValueOf) rejects them; the client library has the same split between mutations/ToStruct and STRUCT parameters.

func RowTypeFromGoType ¶

func RowTypeFromGoType(t reflect.Type) (*sppb.StructType, error)

RowTypeFromGoType is RowTypeFor for a reflect.Type.

func StructColumns ¶

func StructColumns[T any]() ([]string, error)

StructColumns returns the column names derived from T's fields and `spanner` tags, in declaration order, with the same field listing the client library uses for cloud.google.com/go/spanner.Row.ToStruct: exported fields only, embedded struct fields flattened, `spanner:"-"` skipped. Read-only fields (`spanner:"->"` or `spanner:"Name;readonly"`) are included, because they are readable; the write-shaped MutationColumnsAndValues and MutationMap exclude them like the client's mutation constructors do.

It is the spanvalue-side answer to the StructColumns helper requested in https://github.com/googleapis/google-cloud-go/issues/13800, typically used to build the columns argument of Read calls from the same struct passed to ToStruct. T may be a struct or pointer-to-struct type.

package main

import (
	"fmt"

	"github.com/apstndb/spanenc"
)

func main() {
	type Singer struct {
		SingerID  int64 `spanner:"SingerId"`
		FirstName string
		LastName  string
		Internal  string `spanner:"-"`
	}

	columns, err := spanenc.StructColumns[Singer]()
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(columns)
	// client.Single().Read(ctx, "Singers", spanner.AllKeys(), columns) ...
	

Output:

package main

import (
	"fmt"

	"github.com/apstndb/spanenc"
)

func main() {
	type Row struct {
		Gen string `spanner:"Name;readonly"`
	}

	columns, err := spanenc.StructColumns[Row]() // row-shaped: options parsed
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(columns)

	typ, err := spanenc.TypeFor[Row]() // STRUCT-shaped: raw tag, like the client
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(typ.GetStructType().GetFields()[0].GetName())
}

Output:
[Name]
Name;readonly

func StructColumnsAndValues ¶

func StructColumnsAndValues(v any, opts ...EncodeOption) ([]string, []spanner.GenericColumnValue, error)

StructColumnsAndValues converts a struct (or non-nil pointer to struct) into parallel column-name and spanner.GenericColumnValue slices using the ToStruct-shaped field listing (see StructColumns; read-only fields included) and ValueOf for each field. The result feeds GCV-level consumers such as github.com/apstndb/spanvalue/writer's WriteValues or github.com/apstndb/spanvalue.FormatRowColumns for display cells, and stays aligned with RowTypeFor.

For the client library's own mutation constructors, use MutationColumnsAndValues or MutationMap instead, which keep plain Go values, exclude read-only fields, and let the client encode the values.

Options configure the per-field encoding; see WithLossOfPrecisionHandling.

package main

import (
	"fmt"
	"os"

	"github.com/apstndb/spanvalue/writer"

	"github.com/apstndb/spanenc"
)

func main() {
	type Singer struct {
		SingerID  int64 `spanner:"SingerId"`
		FirstName string
	}

	names, values, err := spanenc.StructColumnsAndValues(Singer{SingerID: 1, FirstName: "Marc"})
	if err != nil {
		fmt.Println(err)
		return
	}
	w, err := writer.NewCSVWriter(os.Stdout, writer.WithColumnNames(names))
	if err != nil {
		fmt.Println(err)
		return
	}
	if err := w.WriteValues(names, values); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Flush(); err != nil {
		fmt.Println(err)
		return
	}
}

Output:
SingerId,FirstName
1,Marc

func StructColumnsFromGoType ¶

func StructColumnsFromGoType(t reflect.Type) ([]string, error)

StructColumnsFromGoType is StructColumns for a reflect.Type.

func TypeFor ¶

func TypeFor[T any]() (*sppb.Type, error)

TypeFor returns the sppb.Type that ValueOf would produce for a non-NULL value of Go type T, following the Cloud Spanner client library encoding semantics. See TypeFromGoType.

func TypeFromGoType ¶

func TypeFromGoType(t reflect.Type) (*sppb.Type, error)

TypeFromGoType returns the sppb.Type that ValueOf produces for values of the given Go type, following the Cloud Spanner client library encoding semantics (encodeValue in cloud.google.com/go/spanner).

It returns ErrTypeNotInferable for Go types whose Spanner type depends on the value rather than the type: interface types, cloud.google.com/go/spanner.Encoder implementations, cloud.google.com/go/spanner.GenericColumnValue, cloud.google.com/go/spanner.NullProtoMessage, and cloud.google.com/go/spanner.NullProtoEnum. It returns ErrUnsupportedType for Go types the client library cannot encode.

func ValueOf ¶

func ValueOf(v any, opts ...EncodeOption) (spanner.GenericColumnValue, error)

ValueOf converts a Go value into a spanner.GenericColumnValue, following the Cloud Spanner client library encoding semantics (encodeValue in cloud.google.com/go/spanner): the Go types accepted for statement parameters and mutation values, including the typed NULL rules (nil pointers and nil slices become typed NULLs), spanner.Null* wrappers, spanner.Encoder implementations, protobuf messages and enums, named variants of base types, Go structs as STRUCT values, and spanner.CommitTimestamp.

Deliberate divergences from the client library are listed in the package documentation; most notably an untyped nil returns ErrUntypedNil instead of a NULL without type information.

Options configure encoding per call; see WithLossOfPrecisionHandling for the per-call counterpart of the client's package-global loss-of-precision handling.

package main

import (
	"fmt"

	"github.com/apstndb/spanvalue"

	"github.com/apstndb/spanenc"
)

func main() {
	for _, v := range []any{
		"foo",
		(*int64)(nil),
		[]string{"a", "b"},
	} {
		gcv, err := spanenc.ValueOf(v)
		if err != nil {
			fmt.Println(err)
			return
		}
		s, err := spanvalue.FormatColumnLiteral(gcv)
		if err != nil {
			fmt.Println(err)
			return
		}
		fmt.Println(s)
	}
}

Output:
"foo"
NULL
["a", "b"]

func ValuesFromSlice ¶

func ValuesFromSlice[T any](vs []T, opts ...EncodeOption) (*sppb.Type, []*structpb.Value, error)

ValuesFromSlice converts a homogeneous slice into the shared element sppb.Type and one wire structpb.Value per element. Homogeneity is enforced through the static element type: T must have a type-inferable Spanner type (see TypeFromGoType), so interface element types — which could hold heterogeneous values — are rejected with ErrTypeNotInferable before any element is examined. Each encoded element is additionally verified against the inferred type.

A nil slice returns the element type with a nil values slice. To express a typed NULL ARRAY versus an empty ARRAY at the GCV level, use ArrayValueFromSlice.