Documentation
¶
Overview ¶
Package codec provides a functional approach to encoding and decoding data with validation.
The codec package combines the concepts of encoders and decoders into a unified Type that can both encode values to an output format and decode/validate values from an input format. This is particularly useful for data serialization, API validation, and type-safe transformations.
Core Concepts ¶
Type[A, O, I]: A bidirectional codec that can:
- Decode input I to type A with validation
- Encode type A to output O
- Check if a value is of type A
Validation: Decoding returns Either[Errors, A] which represents:
- Left(Errors): Validation failed with detailed error information
- Right(A): Successfully decoded and validated value
Context: A stack of ContextEntry values that tracks the path through nested structures during validation, providing detailed error messages.
Basic Usage ¶
Creating a simple type:
nilType := codec.MakeNilType[string]()
result := nilType.Decode(nil) // Success
result := nilType.Decode("not nil") // Failure
Composing types with Pipe:
composed := codec.Pipe(typeB)(typeA) // Decodes: I -> A -> B // Encodes: B -> A -> O
Type Parameters ¶
Most functions use three type parameters:
- A: The domain type (the actual Go type being encoded/decoded)
- O: The output type for encoding
- I: The input type for decoding
Validation Errors ¶
ValidationError contains:
- Value: The actual value that failed validation
- Context: The path to the value in nested structures
- Message: Human-readable error description
Integration ¶
This package integrates with:
- optics/decoder: For decoding operations
- optics/encoder: For encoding operations
- either: For validation results
- option: For optional type checking
- reader: For context-dependent operations
Index ¶
- func Is[T any]() func(any) Result[T]
- func Pipe[A, B, O, I any](ab Type[B, A, A]) func(Type[A, O, I]) Type[B, O, I]
- type Codec
- type Context
- type Decode
- type Decoder
- type Either
- type Encode
- type Encoder
- type Endomorphism
- type Lazy
- type Option
- type Pair
- type Reader
- type ReaderResult
- type Result
- type Type
- type Validate
- type Validation
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Is ¶
Is checks if a value can be converted to type T. Returns Some(value) if the conversion succeeds, None otherwise. This is a type-safe cast operation.
func Pipe ¶
func Pipe[A, B, O, I any](ab Type[B, A, A]) func(Type[A, O, I]) Type[B, O, I]
Pipe composes two Types, creating a pipeline where:
- Decoding: I -> A -> B (decode with 'this', then validate with 'ab')
- Encoding: B -> A -> O (encode with 'ab', then encode with 'this')
This allows building complex codecs from simpler ones.
Example:
stringToInt := codec.MakeType(...) // Type[int, string, string] intToPositive := codec.MakeType(...) // Type[PositiveInt, int, int] composed := codec.Pipe(intToPositive)(stringToInt) // Type[PositiveInt, string, string]
Types ¶
type Codec ¶
Codec combines a Decoder and an Encoder for bidirectional transformations. It can decode input I to type A and encode type A to output O.
type Context ¶
type Context = validation.Context
type Decode ¶
type Decode[I, A any] = Reader[I, Validation[A]]
Decode is a function that decodes input I to type A with validation. It returns a Validation result directly.
type Decoder ¶
type Decoder[I, A any] interface { Name() string Validate(I) Reader[Context, Validation[A]] Decode(I) Validation[A] }
Decoder is an interface for types that can decode and validate input.
type Either ¶
Either represents a value that can be one of two types: Left (error) or Right (success).
type Encoder ¶
type Encoder[A, O any] interface { // Encode transforms a value of type A into output format O. Encode(A) O }
Encoder is an interface for types that can encode values.
type Endomorphism ¶
type Endomorphism[A any] = endomorphism.Endomorphism[A]
type Reader ¶
Reader represents a computation that depends on an environment R and produces a value A.
type ReaderResult ¶
type ReaderResult[R, A any] = readerresult.ReaderResult[R, A]
type Type ¶
type Type[A, O, I any] interface { Decoder[I, A] Encoder[A, O] AsDecoder() Decoder[I, A] AsEncoder() Encoder[A, O] Is(any) Result[A] }
Type is a bidirectional codec that combines encoding, decoding, validation, and type checking capabilities. It represents a complete specification of how to work with a particular type.
func MakeSimpleType ¶
func MakeType ¶
func MakeType[A, O, I any]( name string, is Reader[any, Result[A]], validate Validate[I, A], encode Encode[A, O], ) Type[A, O, I]
MakeType creates a new Type with the given name, type checker, validator, and encoder.
Parameters:
- name: A descriptive name for this type (used in error messages)
- is: A function that checks if a value is of type A
- validate: A function that validates and decodes input I to type A
- encode: A function that encodes type A to output O
Returns a Type[A, O, I] that can both encode and decode values.
func Nil ¶
MakeNilType creates a Type that validates nil values. It accepts any input and validates that it is nil, returning a typed nil pointer.
Example:
nilType := codec.MakeNilType[string]()
result := nilType.Decode(nil) // Success: Right((*string)(nil))
result := nilType.Decode("not nil") // Failure: Left(errors)
type Validate ¶
type Validate[I, A any] = Reader[I, Reader[Context, Validation[A]]]
Validate is a function that validates input I to produce type A. It takes an input and returns a Reader that depends on the validation Context.
type Validation ¶
type Validation[A any] = validation.Validation[A]
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package validation provides functional validation types and operations for the codec system.
|
Package validation provides functional validation types and operations for the codec system. |