feat: extend gtsrpc value object docs

foomo/docs/projects/gotsrpc/service-interfaces/value-objects.md

@@ -2,12 +2,17 @@
 sidebar_position: 1
 toc_max_heading_level: 5
 ---
+
 # Value Objects
 
 Typically value objects will be serialized / marshalled as JSON. Please refer to this documentation:
 
 [https://pkg.go.dev/encoding/json#Marshal](https://pkg.go.dev/encoding/json#Marshal)
 
+:::note
+This is just a few basic examples, that show the basics of mapping Go types to idiomatic TypeScript types.
+:::
+
 ## Scalar types
 
 ### Supported in Go and TypeScript
@@ -25,13 +30,11 @@ Typically value objects will be serialized / marshalled as JSON. Please refer to
 
 ### Type Aliases
 
-Go
-```go
+```go title="Go"
 type Greeting string
 ```
 
-TypeScript
-```typescript
+```typescript title="TypeScript"
 type Greeting = string;
 ```
 
@@ -39,8 +42,7 @@ type Greeting = string;
 
 Go does not support enumerations, but `gotsrpc` will translate constants to TypeScripts enums:
 
-Go
-```go
+```go title="Go"
 type Pet string
 
 const (
@@ -58,8 +60,7 @@ const (
 )
 ```
 
-TypeScript
-```typescript
+```typescript title="TypeScript"
 export enum Pet {
   Cat = "cat",
   Dog = "dog",
@@ -72,120 +73,203 @@ export enum SeatCount {
   TwoSeats = 2,
 }
 ```
-
-## Structs / Interfaces
-
-```go
-type Car struct {
-
-}
-```
-
-```typescript
-interface Car {
-
-}
-```
-
 ## Slices
 
 Slices are nilable in Go, thus they can be null in TypeScript. They translate to `Array<T>|null` in TypeScript.
+
 ### Scalar types
 
-```go
+```go title="Go"
 []string
 []int
 // other numeric types
 []bool
 ```
 
-```typescript
-Array<string>|null
-Array<number>|null
+```typescript title="TypeScript"
+Array<string> | null;
+Array<number> | null;
 // all numeric types are numbers
-Array<boolean>|null
+Array<boolean> | null;
 ```
 
 ### Other slice type examples
 
+#### Structs
 
-#### structs
-```go
+```go title="Go"
 []Car
 []*Car
 ```
 
-```typescript
-Array<Car>|null
-Array<Car|null>|null
+```typescript title="TypeScript"
+Array<Car> | null;
+Array<Car | null> | null;
 ```
-#### nested slices
-```go
+
+#### Nested slices
+
+```go title="Go"
 [][]string
 [][]int
 // ...
 ```
 
-```typescript
-Array<Array<string>|null>|null
-Array<Array<number>|null>|null
+```typescript title="TypeScript"
+Array<Array<string> | null> | null;
+Array<Array<number> | null> | null;
 // ...
 ```
 
-
-
 ## Maps / Records
 
 Like slices Go maps are nilable. They translate to `Record<K extends keyof any, T>|null` in TypeScript.
 
+### Scalars
 
-### scalars
-
-```go
+```go title="Go"
 map[string]string
 ```
 
-```typescript
-Record<string,string>|null
+```typescript title="TypeScript"
+Record<string, string> | null;
 ```
 
-### structs
+### Structs
 
-```go
+```go title="Go"
 map[string]*Car
 ```
 
-```typescript
-Record<string,Car|null>|null
+```typescript title="TypeScript"
+Record<string, Car | null> | null;
 ```
 
-### slices
+### Slices
 
-```go
+```go title="Go"
 map[string][]*Car
 ```
 
-```typescript
-Record<string,Array<Car|null>|null>|null
+```typescript title="TypeScript"
+Record<string, Array<Car | null> | null> | null;
 ```
 
-## custom map types
+## Map types
 
 Go and TypeScript support map / Record types:
 
-:::note
+:::tip
 Scalar types / type aliases are of particular value when using maps, because they can add strong semantics:
 :::
 
-```go
+```go title="Go"
 type CarDirectory map[ProductID]*Car
 ```
 
-```typescript
-type CarDirectory = Record<ProductID,Car|null>|null
+```typescript title="TypeScript"
+type CarDirectory = Record<ProductID, Car | null> | null;
 ```
 
+## Nested map types
 
+```go title="Go"
+type BrandID string
+type BrandCarDirectory map[BrandID]map[ProductID]*Car
+// or
+type BrandCarDirectory map[BrandID]CarDirectory
+```
 
+```typescript title="TypeScript"
+type BrandID = string;
+type BrandCarDirectory = Record<
+  BrandID,
+  Record<ProductID, Car | null> | null
+> | null;
+// or
+type BrandCarDirectory = Record<BrandID, CarDirectory> | null;
+```
+## Structs / Interfaces
+
+Arbitrary Types can be composed in structs.
+
+### Field names
+
+Naming conventions are different between Go and TypeScript. In order to bridge the gap between Go and TypeScript Go struct fields can be [annotated with tags](https://pkg.go.dev/encoding/json#Marshal). In this way idiomatic naming of fields can be can be provided for both languages and the translation will be automatic.
+
+#### Default Go => TypeScript
+
+Without json tags TypeScript field names will be like in Go, which is not idiomatic for TypeScript.
+
+```go title="Go"
+type Car struct {
+    GoCase string
+    CamelCase string
+    SnakeCase string
+}
+```
+
+```typescript title="TypeScript"
+interface Car {
+  GoCase:string;
+  CamelCase:string;
+  SnakeCase:string;
+}
+```
+
+#### Idiomatic field names
+
+Json tags allow controlling the name in TypeScript.
+
+```go title="Go"
+type Car struct {
+    CamelCase string `json:"camelCase"`
+    SnakeCase string `json:"snake_case"`
+}
+```
+
+```typescript title="TypeScript"
+interface Car {
+  camelCase:string;
+  snake_case:string;
+}
+```
+
+### Optional and nullable fields
+
+```go title="Go"
+type Basic struct {
+    Value string `json:"value"`
+    OptionalValue string `json:"optionalValue,omitempty"`
+    NullableValue *string `json:"nullableValue"`
+}
+```
+
+```typescript title="TypeScript"
+type Basic interface {
+    value:string;
+    optionalValue?:string;
+    nullableValue:string|null;
+}
+```
+
+### Hiding values from the client
+
+The Go json tag ``` `json:"-"` ``` on a struct  allows it to:
+
+- hide fields from clients
+- prevents clients from setting them in JSON Unmarshalling
+
+```go title="Go"
+type Basic struct {
+    Value string `json:"value"`
+    Secret string `json:"-"`
+}
+```
+
+```typescript title="TypeScript"
+type Basic interface {
+    value:string;
+}
+```
 
-### nested maps