format

func Binary ¶ added in v0.11.0

func Binary(c codex.Codec[[]byte]) Format[[]byte]

Binary returns a Format that reads and writes raw binary data.

It is equivalent to NewTyped[[]byte] with identity marshal and validate+identity unmarshal — bytes are stored and read exactly as they are, without any encoding. Unlike Gob (which adds framing bytes), Binary writes raw bytes that any tool understanding the underlying format (PNG viewer, PDF reader, etc.) can open.

The codec validates the []byte value via [Codec.Refine] constraints on both paths:

• Write: constraints run before the bytes are written; failure returns ports.FileEncodeError (via [ports.File]).
• Read: constraints run after the bytes are read; failure returns ports.FileDecodeError (via [ports.File]).

ContentType defaults to "application/octet-stream"; override with Format.WithContentType.

For typed binary formats where the Go type is not []byte (e.g. image.Image, Protobuf structs) or for write-only formats, use NewTyped directly.

Typical usage:

var pngSignature = []byte{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A}

var pngFile = ports.NewFile(
    "images/{name}.png",
    format.Binary(
        codex.Bytes().
            Refine(validate.MaxBytes(5*1024*1024)).
            Refine(validate.HasPrefix(pngSignature)),
    ).WithContentType("image/png"),
    ports.FilePathParam{Name: "name"},
)

func Gob ¶ added in v0.9.0

func Gob[T any](c codex.Codec[T]) Format[T]

Gob returns a Format[T] that serialises T using encoding/gob.

Unlike JSON, YAML, and TOML — which pass a map[string]any intermediate through the codec — Gob encodes and decodes the typed value directly. Codec constraints are enforced on both marshal (before encoding) and unmarshal (after decoding).

Suitable for internal Go-to-Go communication: forge pipelines, MQTT between Go services, and binary caching. Not suitable for REST content negotiation, human-readable output, or cross-language interoperability.

Requirements and limitations:

• All struct fields that gob encodes must be exported; unexported fields are silently skipped.
• For interface values, register concrete types with encoding/gob.Register before use.
• "application/gob" is a conventional content type; it is not an IANA-registered MIME type.
• Observability is handled by the adapter layer — no special configuration needed.

ContentType is "application/gob".

func JSON ¶

func JSON[T any](c codex.Codec[T]) Format[T]

JSON returns a Format that reads and writes JSON. ContentType is "application/json".

package main

import (
	"fmt"

	"github.com/DaniDeer/go-codex/codex"
	"github.com/DaniDeer/go-codex/format"
)

func main() {
	type Item struct {
		Name  string
		Price float64
	}

	itemCodec := codex.Struct[Item](
		codex.RequiredField("name", codex.String(),
			func(i Item) string { return i.Name },
			func(i *Item, v string) { i.Name = v },
		),
		codex.RequiredField("price", codex.Float64(),
			func(i Item) float64 { return i.Price },
			func(i *Item, v float64) { i.Price = v },
		),
	)

	j := format.JSON(itemCodec)

	// Marshal a Go value to JSON bytes.
	data, _ := j.Marshal(Item{Name: "Widget", Price: 9.99})
	fmt.Println(string(data))

	// Unmarshal JSON bytes back to the typed value.
	item, _ := j.Unmarshal(data)
	fmt.Printf("%s: %.2f\n", item.Name, item.Price)
}

Output:
{"name":"Widget","price":9.99}
Widget: 9.99

func New ¶

func New[T any](c codex.Codec[T], marshal func(any) ([]byte, error), unmarshal func([]byte) (any, error)) Format[T]

New creates a Format from a codec and custom marshal/unmarshal functions. Use this to integrate formats not covered by the built-in constructors. ContentType is empty by default; call Format.WithContentType to set it.

func NewStreamed ¶ added in v0.8.0

func NewStreamed[T any](c codex.Codec[T], marshalTo func(T, io.Writer) error, unmarshal func([]byte) (T, error), contentType string) Format[T]

NewStreamed creates a Format where responses are written directly to an io.Writer without buffering to a []byte intermediate. This enables chunked or streaming responses for large payloads (HTML pages, JSON arrays, CSV exports).

The codec is used for validation: Format.MarshalTo runs all Refine constraints on the value before calling marshalTo, so invalid data is rejected before any bytes are written.

unmarshal is used for Format.Unmarshal (reading streaming formats is rarely needed; pass a function that returns an error when not applicable).

Use Format.IsStreamable to detect streaming formats. The adapter calls Format.MarshalTo instead of Format.Marshal and writes response headers before streaming, so partial output is never flushed on validation failure.

Example — streaming a templ component without buffering:

streamFmt := format.NewStreamed(
    propsCodec,
    func(props Props, w io.Writer) error {
        return component(props).Render(context.Background(), w)
    },
    func([]byte) (Props, error) {
        var zero Props
        return zero, errors.New("HTML is not decodable")
    },
    "text/html; charset=utf-8",
)

func NewTyped ¶ added in v0.8.0

func NewTyped[T any](c codex.Codec[T], marshal func(T) ([]byte, error), unmarshal func([]byte) (T, error), contentType string) Format[T]

NewTyped creates a Format where the marshal and unmarshal functions operate on the typed value directly, rather than on the intermediate representation. The codec is still used for validation: Format.Marshal runs all Refine constraints on the value before calling marshal, and Format.Validate works as normal.

Use this when the wire format cannot be represented via a map[string]any intermediate — for example, rendering HTML via a templ component:

htmlFormat := format.NewTyped(
    propsCodec,
    func(props Props) ([]byte, error) {
        var buf bytes.Buffer
        err := component(props).Render(context.Background(), &buf)
        return buf.Bytes(), err
    },
    func([]byte) (Props, error) {
        var zero Props
        return zero, errors.New("HTML is not decodable")
    },
    "text/html; charset=utf-8",
)

func TOML ¶

func TOML[T any](c codex.Codec[T]) Format[T]

TOML returns a Format that reads and writes TOML. ContentType is "application/toml".

func YAML ¶

func YAML[T any](c codex.Codec[T]) Format[T]

YAML returns a Format that reads and writes YAML. ContentType is "application/yaml".