Interface Codec<T>

Type Parameters:
T - The Java type that this codec is responsible for handling.
All Known Implementing Classes:
CollectionCodec, ConditionalCodec, DescribedCodec, DispatchCodec, EitherCodec, EnumCodec, MapCodec, OneOfCodec, QueryCodec, RecursiveCodec, TupleCodecs.PairCodec, TupleCodecs.Tuple3Codec, TupleCodecs.Tuple4Codec, UnitCodec
public interface Codec<T>
A bidirectional serializer and deserializer capable of translating between Java objects and various serialized formats defined by a DynamicOps provider.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Codec.Decoder<T>
    Functional interface defining the decoding logic of a codec.
    static interface 
    Codec.Encoder<T>
    Functional interface defining the encoding logic of a codec.
    static final record 
    Codec.Pair<A,B>
    Internal definition for an immutable pair of values.
    static final record 
    Codec.Tuple3<A,B,C>
    Internal definition for an immutable sequence of three values.
    static final record 
    Codec.Tuple4<A,B,C,D>
    Internal definition for an immutable sequence of four values.

  • Method Summary

    Modifier and Type
    Method
    Description
    default <R> R
    accept(CodecVisitor<R> visitor)
    Routes this instance into the visitor API to construct contextual schema layouts.
    default <C extends Collection<T>>
    Codec<C>
    collection(Supplier<C> factory)
    Creates a codec for a specific collection implementation.
    default <R> Codec<R>
    comapFlatMap(Function<? super T, ? extends DataResult<? extends R>> to, Function<? super R, ? extends T> from)
    Transforms this codec to handle a new type R, where decoding can fail but encoding cannot.
    static <T> Codec<T>
    conditional(Predicate<T> condition, Codec<T> trueCodec, Codec<T> falseCodec)
    Creates a codec that selects between two codecs based on a condition.
    <D> DataResult<T>
    decode(DynamicOps<D> ops, D input)
    Decodes a serialized input of a specific data format into a Java object.
    default <D> CompletableFuture<DataResult<T>>
    decodeAsync(DynamicOps<D> ops, D input)
    Asynchronously decodes serialized data without blocking the primary thread execution context.
    default String
    describe()
    Outputs a structural description of the expected format for this codec.
    default Codec<T>
    describe(String description)
    Attaches a custom description overriding the default schema output.
    static <K,V> Codec<V>
    dispatch(Class<V> type, String typeKey, Codec<K> keyCodec, Function<? super V, ? extends K> typeGetter, Function<? super K, ? extends Codec<? extends V>> codecGetter)
    Creates a dispatch codec that selects a subtype codec using a discriminator field.
    static <K,V> Codec<V>
    dispatch(String typeKey, Codec<K> keyCodec, Function<? super V, ? extends K> typeGetter, Function<? super K, ? extends Codec<? extends V>> codecGetter)
    Creates a dispatch codec that selects a subtype codec using a discriminator field.
    static <A,B> Codec<Either<A,B>>
    either(Codec<A> left, Codec<B> right)
    Creates a codec for an Either container.
    <D> DataResult<D>
    encode(DynamicOps<D> ops, T value)
    Encodes a Java object into its serialized representation.
    default <D> CompletableFuture<DataResult<D>>
    encodeAsync(DynamicOps<D> ops, T value)
    Asynchronously encodes runtime objects into mapped format bounds.
    static <E extends Enum<E>>
    Codec<E>
    enumCodec(Class<E> enumClass)
    Creates a codec for an Enum type using its string name.
    static <T> Codec<T>
    error(String message)
    Creates a codec that immediately returns an error state upon any encoding or decoding operation.
    static <T> Codec<T>
    fallback(Codec<? extends T> left, Codec<? extends T> right)
    Combines two codecs such that the secondary is used if the primary fails.
    default FieldBuilder<T>
    fieldOf(String name)
    Initiates the definition of a required field for a RecordBuilder.
    default <R> Codec<R>
    flatComapMap(Function<? super T, ? extends R> to, Function<? super R, ? extends DataResult<? extends T>> from)
    Transforms this codec to handle a new type R, where decoding cannot fail but encoding can.
    default <R> Codec<R>
    flatXmap(Function<? super T, ? extends DataResult<? extends R>> to, Function<? super R, ? extends DataResult<? extends T>> from)
    Transforms this codec to handle a new type R, where both decoding and encoding can fail.
    default Codec<List<T>>
    immutableList()
    Creates a codec for an immutable List of elements of type T.
    static <K,V> Codec<Map<K,V>>
    immutableMap(Codec<K> keyCodec, Codec<V> valueCodec)
    Creates an immutable map codec structure mapping rigid configuration values safely.
    default Codec<Set<T>>
    immutableSet()
    Creates a codec for an immutable Set of elements of type T.
    default Codec<List<T>>
    list()
    Creates a codec for a mutable List of elements of type T.
    static <K,V> Codec<Map<K,V>>
    map(Codec<K> keyCodec, Codec<V> valueCodec)
    Creates a mutable map codec structure mapping identical type variants.
    default Codec<T>
    maxLength(int length)
    Shorthand restricting a string or collection codec to a maximum elemental length.
    default Codec<T>
    minLength(int length)
    Shorthand restricting a string or collection codec to a minimum elemental length.
    default Codec<T>
    nullable()
    Modifies the codec to treat null Java values as empty serialized states.
    static <T> Codec<T>
    of(Codec.Decoder<T> decoder, Codec.Encoder<T> encoder)
    Factory method to create a codec using explicit context-aware decoders and encoders.
    static <T> Codec<T>
    of(Function<Object,T> decoder, Function<T,Object> encoder)
    Factory method to create a simple codec from mapping functions.
    static <T> Codec<T>
    oneOf(Codec<? extends T>... codecs)
    Combines multiple codecs to be tried in sequence.
    static <T> Codec<T>
    oneOf(Class<T> type, Codec<? extends T>... codecs)
    Combines multiple codecs to be tried in sequence, explicitly anchoring the type.
    default Codec<T>
    oneOf(T... values)
    Shorthand confining valid interpretation explicitly to arbitrary hardcoded structural objects.
    default Codec<Optional<T>>
    optional()
    Wraps the current codec to handle Java Optional values.
    default FieldBuilder<Optional<T>>
    optionalFieldOf(String name)
    Initiates the definition of an optional field for a RecordBuilder.
    default FieldBuilder<T>
    optionalFieldOf(String name, T defaultValue)
    Initiates the definition of an optional field with a default fallback value.
    default Codec<T>
    orElse(T defaultValue)
    Wraps this codec with a default value to be used if decoding fails or returns null.
    static <A,B> Codec<Codec.Pair<A,B>>
    pair(Codec<A> first, Codec<B> second)
    Creates a codec capable of handling a two-element ordered sequence.
    default Codec<T>
    positive()
    Shorthand requiring numerical mapping bounds to be universally structured above zero.
    static <T> Codec<T>
    query(Codec<T> codec, String path)
    Creates a codec that operates on a nested path within the input structure.
    default Codec<T>
    range(double min, double max)
    Shorthand trapping generic numerical values inside deterministic operational ranges structurally.
    static <T> Codec<T>
    recursive(Class<T> type, Function<Codec<T>,Codec<T>> builder)
    Constructs a codec capable of resolving cyclic dependencies correctly, explicitly anchoring the type.
    static <T> Codec<T>
    recursive(Function<Codec<T>,Codec<T>> builder)
    Constructs a codec capable of resolving cyclic dependencies correctly.
    default Codec<T>
    regex(String pattern)
    Shorthand checking string codecs against arbitrary explicit formatting configurations.
    default Codec<T>
    restrict(Consumer<SchemaValidator> configurator)
    Applies schema-based validation to encoded and decoded values.
    default SchemaNode
    schema()
    Generates the schema representation for this codec.
    default Codec<Set<T>>
    set()
    Creates a codec for a mutable Set of elements of type T.
    default <D> boolean
    structuralEquals(DynamicOps<D> ops, T a, T b)
    Computes structural equality between two decoded values by encoding and comparing their serialized variants.
    static <K extends Enum<K>, V>
    Codec<V>
    taggedUnion(Class<V> type, String typeKey, Codec<K> keyCodec, Function<? super V, ? extends K> typeGetter, Function<? super K, ? extends Codec<? extends V>> codecGetter)
    Creates a tagged union codec using an enum discriminator field.
    static <K extends Enum<K>, V>
    Codec<V>
    taggedUnion(String typeKey, Codec<K> keyCodec, Function<? super V, ? extends K> typeGetter, Function<? super K, ? extends Codec<? extends V>> codecGetter)
    Creates a tagged union codec using an enum discriminator field.
    default Codec<T>
    transform(Function<T,T> mapper)
    Simplifies mapping the value via an identical forward and backward translation.
    static <A,B,C> Codec<Codec.Tuple3<A,B,C>>
    tuple(Codec<A> first, Codec<B> second, Codec<C> third)
    Creates a codec handling a three-element ordered sequence.
    static <A,B,C,D_TYPE>
    Codec<Codec.Tuple4<A,B,C,D_TYPE>>
    tuple(Codec<A> first, Codec<B> second, Codec<C> third, Codec<D_TYPE> fourth)
    Creates a codec handling a four-element ordered sequence.
    default <U> Codec<U>
    unchecked()
    Performs an unsafe cast of this codec to another type.
    static <T> Codec<T>
    unit(Supplier<T> value)
    Creates a codec that reliably yields the same predefined value during decoding, and maps to an empty representation during encoding.
    static <T> Codec<T>
    unit(T value)
    Creates a codec that reliably yields the same predefined value during decoding.
    default Codec<T>
    validate(Function<? super T, ? extends DataResult<T>> validator)
    Validates decoded and encoded objects using a singular validation block.
    default Codec<T>
    validate(Predicate<T> condition, Function<T,String> errorMessage)
    Conditionally validates inputs ensuring they fulfill programmatic rules.
    default Codec<T>
    versioned(net.kyori.adventure.key.Key id, DataFixerRegistry registry)
    Wraps this codec in a versioned container format.
    default Codec<T>
    withSchema(SchemaNode schema)
    Associates a custom schema with this codec.
    default <R> Codec<R>
    xmap(Function<? super T, ? extends R> forward, Function<? super R, ? extends T> backward)
    Transforms this codec to handle a new type R via two-way conversion functions.

  • Method Details

    • decode

      <D> DataResult<T> decode(DynamicOps<D> ops, D input)
      Decodes a serialized input of a specific data format into a Java object.
      Type Parameters:
      D - The type of the serialized data.
      Parameters:
      ops - The provider defining how to navigate and read data of type D.
      input - The raw serialized input to be processed.
      Returns:
      A DataResult containing the decoded object or an error state.

    • encode

      <D> DataResult<D> encode(DynamicOps<D> ops, T value)
      Encodes a Java object into its serialized representation.
      Type Parameters:
      D - The target type of the serialized data.
      Parameters:
      ops - The provider defining how to construct data of type D.
      value - The Java object instance to be serialized.
      Returns:
      A DataResult containing the serialized data or an error state.

    • accept

      default <R> R accept(CodecVisitor<R> visitor)
      Routes this instance into the visitor API to construct contextual schema layouts.
      Type Parameters:
      R - The layout target natively returning explicitly mapped variants.
      Parameters:
      visitor - The evaluation logic instance.
      Returns:
      Evaluated variant functionally extracting outputs.

    • schema

      default SchemaNode schema()
      Generates the schema representation for this codec.
      Returns:
      The generated schema node.

    • withSchema

      default Codec<T> withSchema(SchemaNode schema)
      Associates a custom schema with this codec. The provided schema is used instead of the automatically generated schema.
      Parameters:
      schema - The schema to associate with this codec.
      Returns:
      A codec that exposes the provided schema.

    • decodeAsync

      default <D> CompletableFuture<DataResult<T>> decodeAsync(DynamicOps<D> ops, D input)
      Asynchronously decodes serialized data without blocking the primary thread execution context.
      Type Parameters:
      D - The type of the serialized data format.
      Parameters:
      ops - The provider defining operations layout boundaries.
      input - The target structured format representing object mapping targets.
      Returns:
      A CompletableFuture housing the localized data result.

    • encodeAsync

      default <D> CompletableFuture<DataResult<D>> encodeAsync(DynamicOps<D> ops, T value)
      Asynchronously encodes runtime objects into mapped format bounds.
      Type Parameters:
      D - The target format mapping representation type.
      Parameters:
      ops - The operational binding interface interpreting physical output rules.
      value - The physical target structure mapping variables.
      Returns:
      A CompletableFuture housing the target data layout.

    • describe

      default String describe()
      Outputs a structural description of the expected format for this codec. Useful for schema generation and validation debugging.
      Returns:
      The schema definition representing the target type.

    • describe

      default Codec<T> describe(String description)
      Attaches a custom description overriding the default schema output.
      Parameters:
      description - The new schema description.
      Returns:
      A structurally identical Codec containing the customized description.

    • structuralEquals

      default <D> boolean structuralEquals(DynamicOps<D> ops, T a, T b)
      Computes structural equality between two decoded values by encoding and comparing their serialized variants. Useful when the target object lacks a proper Object.equals(Object) definition.
      Type Parameters:
      D - The dynamic operations context.
      Parameters:
      ops - The target serialization provider.
      a - The primary value to compare.
      b - The secondary value to compare against.
      Returns:
      True if both values yield the same serialized form.

    • fieldOf

      default FieldBuilder<T> fieldOf(String name)
      Initiates the definition of a required field for a RecordBuilder.
      Parameters:
      name - The key identifier for this field in the serialized format.
      Returns:
      A builder to bind the field to a getter function.

    • optionalFieldOf

      default FieldBuilder<Optional<T>> optionalFieldOf(String name)
      Initiates the definition of an optional field for a RecordBuilder. If the field is missing during decoding, the codec resolves to Optional.empty().
      Parameters:
      name - The key identifier for this field in the serialized format.
      Returns:
      A builder to bind the field to a getter function.

    • optionalFieldOf

      default FieldBuilder<T> optionalFieldOf(String name, T defaultValue)
      Initiates the definition of an optional field with a default fallback value.
      Parameters:
      name - The key identifier for this field in the serialized format.
      defaultValue - The value to yield if the key is missing.
      Returns:
      A builder to bind the field to a getter function.

    • taggedUnion

      static <K extends Enum<K>, V> Codec<V> taggedUnion(String typeKey, Codec<K> keyCodec, Function<? super V, ? extends K> typeGetter, Function<? super K, ? extends Codec<? extends V>> codecGetter)
      Creates a tagged union codec using an enum discriminator field.
      Parameters:
      typeKey - The field containing the discriminator.
      keyCodec - Codec for the discriminator type.
      typeGetter - Function extracting the discriminator from a value.
      codecGetter - Function providing the codec for a discriminator.
      Returns:
      A tagged union codec.

    • taggedUnion

      static <K extends Enum<K>, V> Codec<V> taggedUnion(Class<V> type, String typeKey, Codec<K> keyCodec, Function<? super V, ? extends K> typeGetter, Function<? super K, ? extends Codec<? extends V>> codecGetter)
      Creates a tagged union codec using an enum discriminator field.
      Parameters:
      type - The base type.
      typeKey - The field containing the discriminator.
      keyCodec - Codec for the discriminator type.
      typeGetter - Function extracting the discriminator from a value.
      codecGetter - Function providing the codec for a discriminator.
      Returns:
      A tagged union codec.

    • pair

      static <A,B> Codec<Codec.Pair<A,B>> pair(Codec<A> first, Codec<B> second)
      Creates a codec capable of handling a two-element ordered sequence.
      Type Parameters:
      A - The type of the first value.
      B - The type of the second value.
      Parameters:
      first - Codec for the first branch.
      second - Codec for the second branch.
      Returns:
      A codec for a paired structure.

    • tuple

      static <A,B,C> Codec<Codec.Tuple3<A,B,C>> tuple(Codec<A> first, Codec<B> second, Codec<C> third)
      Creates a codec handling a three-element ordered sequence.
      Type Parameters:
      A - The type of the first value.
      B - The type of the second value.
      C - The type of the third value.
      Parameters:
      first - Codec for the first branch.
      second - Codec for the second branch.
      third - Codec for the third branch.
      Returns:
      A codec for a Tuple3 structure.

    • tuple

      static <A,B,C,D_TYPE> Codec<Codec.Tuple4<A,B,C,D_TYPE>> tuple(Codec<A> first, Codec<B> second, Codec<C> third, Codec<D_TYPE> fourth)
      Creates a codec handling a four-element ordered sequence.
      Type Parameters:
      A - The type of the first value.
      B - The type of the second value.
      C - The type of the third value.
      D_TYPE - The type of the fourth value.
      Parameters:
      first - Codec for the first branch.
      second - Codec for the second branch.
      third - Codec for the third branch.
      fourth - Codec for the fourth branch.
      Returns:
      A codec for a Tuple4 structure.

    • unit

      static <T> Codec<T> unit(Supplier<T> value)
      Creates a codec that reliably yields the same predefined value during decoding, and maps to an empty representation during encoding.
      Type Parameters:
      T - The type of the value.
      Parameters:
      value - The supplier yielding the constant value.
      Returns:
      A unit codec.

    • unit

      static <T> Codec<T> unit(T value)
      Creates a codec that reliably yields the same predefined value during decoding.
      Type Parameters:
      T - The type of the value.
      Parameters:
      value - The constant value.
      Returns:
      A unit codec.

    • query

      static <T> Codec<T> query(Codec<T> codec, String path)
      Creates a codec that operates on a nested path within the input structure.
      Parameters:
      codec - The codec used to read and write the nested value.
      path - The target path.
      Returns:
      A path-constrained codec.

    • conditional

      static <T> Codec<T> conditional(Predicate<T> condition, Codec<T> trueCodec, Codec<T> falseCodec)
      Creates a codec that selects between two codecs based on a condition.
      Parameters:
      condition - The condition used to choose a codec.
      trueCodec - Codec used when the condition is true.
      falseCodec - Codec used when the condition is false.
      Returns:
      A conditional codec.

    • error

      static <T> Codec<T> error(String message)
      Creates a codec that immediately returns an error state upon any encoding or decoding operation.
      Type Parameters:
      T - The target Java type.
      Parameters:
      message - The specific error reason.
      Returns:
      A failing Codec implementation.

    • of

      static <T> Codec<T> of(Codec.Decoder<T> decoder, Codec.Encoder<T> encoder)
      Factory method to create a codec using explicit context-aware decoders and encoders.
      Type Parameters:
      T - The target Java type.
      Parameters:
      decoder - Function to read data utilizing the provided DynamicOps.
      encoder - Function to write data utilizing the provided DynamicOps.
      Returns:
      A custom Codec implementation.

    • of

      static <T> Codec<T> of(Function<Object,T> decoder, Function<T,Object> encoder)
      Factory method to create a simple codec from mapping functions.
      Type Parameters:
      T - The target Java type.
      Parameters:
      decoder - Function to convert raw objects (from DynamicOps) to type T.
      encoder - Function to convert type T to raw objects.
      Returns:
      A basic Codec implementation.

    • map

      static <K,V> Codec<Map<K,V>> map(Codec<K> keyCodec, Codec<V> valueCodec)
      Creates a mutable map codec structure mapping identical type variants.
      Type Parameters:
      K - Key type.
      V - Value type.
      Parameters:
      keyCodec - Codec for keys.
      valueCodec - Codec for values.
      Returns:
      A codec handling map derivations natively.

    • immutableMap

      static <K,V> Codec<Map<K,V>> immutableMap(Codec<K> keyCodec, Codec<V> valueCodec)
      Creates an immutable map codec structure mapping rigid configuration values safely.
      Type Parameters:
      K - Key type.
      V - Value type.
      Parameters:
      keyCodec - Codec for keys.
      valueCodec - Codec for values.
      Returns:
      An immutable codec handling map derivations natively.

    • enumCodec

      static <E extends Enum<E>> Codec<E> enumCodec(Class<E> enumClass)
      Creates a codec for an Enum type using its string name.
      Type Parameters:
      E - Enum type.
      Parameters:
      enumClass - The class literal of the enum.
      Returns:
      A codec for the specified enum.

    • fallback

      static <T> Codec<T> fallback(Codec<? extends T> left, Codec<? extends T> right)
      Combines two codecs such that the secondary is used if the primary fails.
      Type Parameters:
      T - Target type.
      Parameters:
      left - Primary codec.
      right - Fallback codec.
      Returns:
      A fallback-enabled codec.

    • either

      static <A,B> Codec<Either<A,B>> either(Codec<A> left, Codec<B> right)
      Creates a codec for an Either container.
      Type Parameters:
      A - Left branch type.
      B - Right branch type.
      Parameters:
      left - Codec for type A.
      right - Codec for type B.
      Returns:
      A codec for Either.

    • oneOf

      @SafeVarargs static <T> Codec<T> oneOf(Codec<? extends T>... codecs)
      Combines multiple codecs to be tried in sequence.
      Type Parameters:
      T - Target type.
      Parameters:
      codecs - Array of codecs to attempt.
      Returns:
      A multi-branch codec.

    • oneOf

      @SafeVarargs static <T> Codec<T> oneOf(Class<T> type, Codec<? extends T>... codecs)
      Combines multiple codecs to be tried in sequence, explicitly anchoring the type.
      Type Parameters:
      T - Target type.
      Parameters:
      type - The class literal representing the target type.
      codecs - Array of codecs to attempt.
      Returns:
      A multi-branch codec.

    • recursive

      static <T> Codec<T> recursive(Function<Codec<T>,Codec<T>> builder)
      Constructs a codec capable of resolving cyclic dependencies correctly.
      Type Parameters:
      T - The target Java type.
      Parameters:
      builder - A function yielding the codec upon execution.
      Returns:
      A proper recursive Codec utilizing lazy evaluation.

    • recursive

      static <T> Codec<T> recursive(Class<T> type, Function<Codec<T>,Codec<T>> builder)
      Constructs a codec capable of resolving cyclic dependencies correctly, explicitly anchoring the type.
      Type Parameters:
      T - The target Java type.
      Parameters:
      type - The class literal representing the target type.
      builder - A function yielding the codec upon execution.
      Returns:
      A proper recursive Codec utilizing lazy evaluation explicitly bound.

    • dispatch

      static <K,V> Codec<V> dispatch(String typeKey, Codec<K> keyCodec, Function<? super V, ? extends K> typeGetter, Function<? super K, ? extends Codec<? extends V>> codecGetter)
      Creates a dispatch codec that selects a subtype codec using a discriminator field.
      Parameters:
      typeKey - The discriminator field name.
      keyCodec - Codec for the discriminator type.
      typeGetter - Function extracting the discriminator from a value.
      codecGetter - Function providing the codec for a discriminator.
      Returns:
      A dispatch codec.

    • dispatch

      static <K,V> Codec<V> dispatch(Class<V> type, String typeKey, Codec<K> keyCodec, Function<? super V, ? extends K> typeGetter, Function<? super K, ? extends Codec<? extends V>> codecGetter)
      Creates a dispatch codec that selects a subtype codec using a discriminator field.
      Parameters:
      type - The base type.
      typeKey - The discriminator field name.
      keyCodec - Codec for the discriminator type.
      typeGetter - Function extracting the discriminator from a value.
      codecGetter - Function providing the codec for a discriminator.
      Returns:
      A dispatch codec.

    • xmap

      default <R> Codec<R> xmap(Function<? super T, ? extends R> forward, Function<? super R, ? extends T> backward)
      Transforms this codec to handle a new type R via two-way conversion functions.
      Type Parameters:
      R - The new target Java type.
      Parameters:
      forward - Conversion function from T to R.
      backward - Conversion function from R to T.
      Returns:
      A codec for type R.

    • flatXmap

      default <R> Codec<R> flatXmap(Function<? super T, ? extends DataResult<? extends R>> to, Function<? super R, ? extends DataResult<? extends T>> from)
      Transforms this codec to handle a new type R, where both decoding and encoding can fail.
      Type Parameters:
      R - The new target Java type.
      Parameters:
      to - Conversion function from T to DataResult R.
      from - Conversion function from R to DataResult T.
      Returns:
      A flat-mapped codec returning contextual results.

    • comapFlatMap

      default <R> Codec<R> comapFlatMap(Function<? super T, ? extends DataResult<? extends R>> to, Function<? super R, ? extends T> from)
      Transforms this codec to handle a new type R, where decoding can fail but encoding cannot.
      Type Parameters:
      R - The new target Java type.
      Parameters:
      to - Conversion function from T to DataResult R.
      from - Conversion function from R to T.
      Returns:
      A codec for type R validated during decoding.

    • flatComapMap

      default <R> Codec<R> flatComapMap(Function<? super T, ? extends R> to, Function<? super R, ? extends DataResult<? extends T>> from)
      Transforms this codec to handle a new type R, where decoding cannot fail but encoding can.
      Type Parameters:
      R - The new target Java type.
      Parameters:
      to - Conversion function from T to R.
      from - Conversion function from R to DataResult T.
      Returns:
      A codec for type R validated during encoding.

    • transform

      default Codec<T> transform(Function<T,T> mapper)
      Simplifies mapping the value via an identical forward and backward translation.
      Parameters:
      mapper - The mapping function ensuring type isolation.
      Returns:
      A transformed codec reflecting isomorphic states.

    • restrict

      default Codec<T> restrict(Consumer<SchemaValidator> configurator)
      Applies schema-based validation to encoded and decoded values.
      Parameters:
      configurator - Consumer used to configure validation rules.
      Returns:
      A validating codec.

    • validate

      default Codec<T> validate(Function<? super T, ? extends DataResult<T>> validator)
      Validates decoded and encoded objects using a singular validation block.
      Parameters:
      validator - The validation logic yielding a DataResult.
      Returns:
      A validated codec preventing illegal structural states.

    • validate

      default Codec<T> validate(Predicate<T> condition, Function<T,String> errorMessage)
      Conditionally validates inputs ensuring they fulfill programmatic rules.
      Parameters:
      condition - The required constraint.
      errorMessage - The contextual reason for constraint failures.
      Returns:
      A validating codec enforcing behavioral restrictions.

    • minLength

      default Codec<T> minLength(int length)
      Shorthand restricting a string or collection codec to a minimum elemental length.
      Parameters:
      length - The lower limit element bounds.
      Returns:
      A restricted schema variant.

    • maxLength

      default Codec<T> maxLength(int length)
      Shorthand restricting a string or collection codec to a maximum elemental length.
      Parameters:
      length - The upper limit element bounds.
      Returns:
      A restricted schema variant.

    • regex

      default Codec<T> regex(String pattern)
      Shorthand checking string codecs against arbitrary explicit formatting configurations.
      Parameters:
      pattern - The required mapping sequence matching strings precisely.
      Returns:
      A restricted schema variant.

    • range

      default Codec<T> range(double min, double max)
      Shorthand trapping generic numerical values inside deterministic operational ranges structurally.
      Parameters:
      min - The explicit minimum value configuration limit.
      max - The explicit maximum value configuration limit.
      Returns:
      A restricted schema variant.

    • positive

      default Codec<T> positive()
      Shorthand requiring numerical mapping bounds to be universally structured above zero.
      Returns:
      A restricted schema variant.

    • oneOf

      default Codec<T> oneOf(T... values)
      Shorthand confining valid interpretation explicitly to arbitrary hardcoded structural objects.
      Parameters:
      values - The deterministic array defining possible resolutions.
      Returns:
      A restricted schema variant.

    • orElse

      default Codec<T> orElse(T defaultValue)
      Wraps this codec with a default value to be used if decoding fails or returns null.
      Parameters:
      defaultValue - The value to return on failure.
      Returns:
      A codec that provides a default result.

    • list

      default Codec<List<T>> list()
      Creates a codec for a mutable List of elements of type T.
      Returns:
      A codec for a List of T.

    • immutableList

      default Codec<List<T>> immutableList()
      Creates a codec for an immutable List of elements of type T.
      Returns:
      An immutable List codec.

    • set

      default Codec<Set<T>> set()
      Creates a codec for a mutable Set of elements of type T.
      Returns:
      A codec for a Set of T.

    • immutableSet

      default Codec<Set<T>> immutableSet()
      Creates a codec for an immutable Set of elements of type T.
      Returns:
      An immutable Set codec.

    • unchecked

      default <U> Codec<U> unchecked()
      Performs an unsafe cast of this codec to another type.
      Type Parameters:
      U - Target type.
      Returns:
      The same codec instance cast to Codec of U.

    • collection

      default <C extends Collection<T>> Codec<C> collection(Supplier<C> factory)
      Creates a codec for a specific collection implementation.
      Type Parameters:
      C - The specific collection type.
      Parameters:
      factory - Supplier to create a new collection instance.
      Returns:
      A collection-specific codec.

    • optional

      default Codec<Optional<T>> optional()
      Wraps the current codec to handle Java Optional values.
      Returns:
      A codec for Optional of T.

    • nullable

      default Codec<T> nullable()
      Modifies the codec to treat null Java values as empty serialized states.
      Returns:
      A null-safe version of this codec.

    • versioned

      default Codec<T> versioned(net.kyori.adventure.key.Key id, DataFixerRegistry registry)
      Wraps this codec in a versioned container format. Automatically applies migrations via the DataFixerRegistry before decoding.
      Parameters:
      id - The unique identifier for the data fixer.
      registry - The orchestrator that handles the migration logic.
      Returns:
      A version-aware codec.