Encoding and Codecs

/**
 * Bidirectional encoder/decoder interface
 */
interface Codec<TFrom, TTo = TFrom> {
  encode(value: TFrom): TTo;
  decode(value: TTo): TFrom;
}

/**
 * One-way encoding interface
 */
interface Encoder<TFrom, TTo = TFrom> {
  encode(value: TFrom): TTo;
}

/**
 * One-way decoding interface
 */
interface Decoder<TFrom, TTo = TFrom> {
  decode(value: TFrom): TTo;
}

/**
 * Fixed-size codec with known byte length
 */
interface FixedSizeCodec<TFrom, TTo = TFrom> extends Codec<TFrom, TTo> {
  fixedSize: number;
}

/**
 * Variable-size codec with dynamic length
 */
interface VariableSizeCodec<TFrom, TTo = TFrom> extends Codec<TFrom, TTo> {
  getSizeFromValue(value: TFrom): number;
  maxSize?: number;
}

/**
 * Immutable byte array type
 */
type ReadonlyUint8Array = Readonly<Uint8Array>;

/**
 * Combine separate encoder and decoder into codec
 * @param encoder - Encoder function
 * @param decoder - Decoder function
 * @returns Combined codec
 */
function combineCodec<TFrom, TTo>(
  encoder: Encoder<TFrom, TTo>,
  decoder: Decoder<TTo, TFrom>
): Codec<TFrom, TTo>;

/**
 * Fix codec to specific byte size
 * @param codec - Codec to fix size
 * @param size - Fixed size in bytes
 * @returns Fixed-size codec
 */
function fixCodecSize<TFrom, TTo>(
  codec: Codec<TFrom, TTo>,
  size: number
): FixedSizeCodec<TFrom, TTo>;

/**
 * Transform codec values through mapping functions
 * @param codec - Base codec
 * @param transform - Transform functions
 * @returns Transformed codec
 */
function transformCodec<TFrom, TTo, UFrom, UTo>(
  codec: Codec<TFrom, TTo>,
  transform: {
    encode: (value: UFrom) => TFrom;
    decode: (value: TTo) => UTo;
  }
): Codec<UFrom, UTo>;

/**
 * Reverse byte order in codec output
 * @param codec - Codec to reverse
 * @returns Codec with reversed byte order
 */
function reverseCodec<T>(codec: Codec<T, Uint8Array>): Codec<T, Uint8Array>;

/**
 * Add padding to codec output
 * @param codec - Codec to pad
 * @param size - Target size with padding
 * @returns Padded codec
 */
function padCodec<T>(codec: Codec<T, Uint8Array>, size: number): Codec<T, Uint8Array>;

/**
 * Unsigned 8-bit integer codec
 */
function getU8Codec(): FixedSizeCodec<number, Uint8Array>;

/**
 * Unsigned 16-bit integer codec
 */
function getU16Codec(endian?: 'le' | 'be'): FixedSizeCodec<number, Uint8Array>;

/**
 * Unsigned 32-bit integer codec
 */
function getU32Codec(endian?: 'le' | 'be'): FixedSizeCodec<number, Uint8Array>;

/**
 * Unsigned 64-bit integer codec
 */
function getU64Codec(endian?: 'le' | 'be'): FixedSizeCodec<bigint, Uint8Array>;

/**
 * Unsigned 128-bit integer codec
 */
function getU128Codec(endian?: 'le' | 'be'): FixedSizeCodec<bigint, Uint8Array>;

/**
 * Signed 8-bit integer codec
 */
function getI8Codec(): FixedSizeCodec<number, Uint8Array>;

/**
 * Signed 16-bit integer codec
 */
function getI16Codec(endian?: 'le' | 'be'): FixedSizeCodec<number, Uint8Array>;

/**
 * Signed 32-bit integer codec
 */
function getI32Codec(endian?: 'le' | 'be'): FixedSizeCodec<number, Uint8Array>;

/**
 * Signed 64-bit integer codec
 */
function getI64Codec(endian?: 'le' | 'be'): FixedSizeCodec<bigint, Uint8Array>;

/**
 * 32-bit floating point codec
 */
function getF32Codec(endian?: 'le' | 'be'): FixedSizeCodec<number, Uint8Array>;

/**
 * 64-bit floating point codec
 */
function getF64Codec(endian?: 'le' | 'be'): FixedSizeCodec<number, Uint8Array>;

/**
 * Compact 16-bit integer codec (variable length)
 */
function getShortU16Codec(): VariableSizeCodec<number, Uint8Array>;

import { getU64Codec, getU32Codec } from "@solana/web3.js";

// Encode numbers to bytes
const u64Codec = getU64Codec();
const lamportsBytes = u64Codec.encode(1000000000n);
console.log("Encoded lamports:", lamportsBytes);

// Decode bytes back to numbers
const decodedLamports = u64Codec.decode(lamportsBytes);
console.log("Decoded lamports:", decodedLamports);

// Combine multiple number codecs
const u32Codec = getU32Codec();
const blockHeight = u32Codec.encode(150000000);

/**
 * UTF-8 string codec
 */
function getUtf8Codec(): VariableSizeCodec<string, Uint8Array>;

/**
 * Base58 encoding codec
 */
function getBase58Codec(): Codec<string, Uint8Array>;

/**
 * Base64 encoding codec
 */
function getBase64Codec(): Codec<string, Uint8Array>;

/**
 * Base16 (hexadecimal) encoding codec
 */
function getBase16Codec(): Codec<string, Uint8Array>;

/**
 * Base10 (decimal) encoding codec
 */
function getBase10Codec(): Codec<string, Uint8Array>;

/**
 * Custom base encoding codec
 * @param alphabet - Character alphabet for encoding
 * @returns BaseX codec
 */
function getBaseXCodec(alphabet: string): Codec<string, Uint8Array>;

/**
 * Null-terminated string codec
 */
function getNullCharactersCodec(): VariableSizeCodec<string, Uint8Array>;

import { getBase58Codec, getUtf8Codec } from "@solana/web3.js";

// Encode/decode addresses
const base58Codec = getBase58Codec();
const addressBytes = base58Codec.encode("11111111111111111111111111111112");
const decodedAddress = base58Codec.decode(addressBytes);

// Encode/decode text data
const utf8Codec = getUtf8Codec();
const textBytes = utf8Codec.encode("Hello, Solana!");
const decodedText = utf8Codec.decode(textBytes);

/**
 * Array codec for homogeneous collections
 * @param itemCodec - Codec for array items
 * @param config - Optional array configuration
 * @returns Array codec
 */
function getArrayCodec<T>(
  itemCodec: Codec<T, Uint8Array>,
  config?: {
    size?: FixedSizeCodec<number, Uint8Array> | number;
  }
): VariableSizeCodec<T[], Uint8Array>;

/**
 * Set codec for unique collections
 * @param itemCodec - Codec for set items
 * @returns Set codec
 */
function getSetCodec<T>(
  itemCodec: Codec<T, Uint8Array>
): VariableSizeCodec<Set<T>, Uint8Array>;

/**
 * Map codec for key-value pairs
 * @param keyCodec - Codec for keys
 * @param valueCodec - Codec for values
 * @returns Map codec
 */
function getMapCodec<K, V>(
  keyCodec: Codec<K, Uint8Array>,
  valueCodec: Codec<V, Uint8Array>
): VariableSizeCodec<Map<K, V>, Uint8Array>;

/**
 * Struct codec for object types
 * @param fields - Field codecs
 * @returns Struct codec
 */
function getStructCodec<T>(
  fields: StructCodecConfig<T>
): FixedSizeCodec<T, Uint8Array> | VariableSizeCodec<T, Uint8Array>;

/**
 * Tuple codec for fixed arrays
 * @param codecs - Codecs for tuple elements
 * @returns Tuple codec
 */
function getTupleCodec<T extends readonly unknown[]>(
  codecs: TupleCodecConfig<T>
): FixedSizeCodec<T, Uint8Array>;

/**
 * Enum codec for discriminated unions
 * @param variants - Variant configurations
 * @returns Enum codec
 */
function getEnumCodec<T>(
  variants: EnumCodecConfig<T>
): VariableSizeCodec<T, Uint8Array>;

/**
 * Union codec for tagged unions
 * @param variants - Union variant codecs
 * @returns Union codec
 */
function getUnionCodec<T>(
  variants: UnionCodecConfig<T>
): VariableSizeCodec<T, Uint8Array>;

import { 
  getStructCodec, 
  getArrayCodec, 
  getU64Codec,
  getUtf8Codec,
  getAddressCodec
} from "@solana/web3.js";

// Define token account structure
interface TokenAccount {
  mint: Address;
  owner: Address;
  amount: bigint;
  state: number;
}

// Create struct codec
const tokenAccountCodec = getStructCodec({
  mint: getAddressCodec(),
  owner: getAddressCodec(), 
  amount: getU64Codec(),
  state: getU8Codec()
});

// Encode token account
const tokenAccount: TokenAccount = {
  mint: address("mint-address"),
  owner: address("owner-address"),
  amount: 1000000n,
  state: 1
};

const encodedAccount = tokenAccountCodec.encode(tokenAccount);
const decodedAccount = tokenAccountCodec.decode(encodedAccount);

/**
 * Option type for optional values
 */
type Option<T> = { __kind: 'Some'; value: T } | { __kind: 'None' };

/**
 * Create Some option value
 * @param value - Value to wrap
 * @returns Some option
 */
function option<T>(value: T): Option<T>;

/**
 * Create None option value
 * @returns None option
 */
function none<T>(): Option<T>;

/**
 * Check if option is Some
 * @param option - Option to check
 * @returns True if Some
 */
function isSome<T>(option: Option<T>): option is { __kind: 'Some'; value: T };

/**
 * Check if option is None
 * @param option - Option to check
 * @returns True if None
 */
function isNone<T>(option: Option<T>): option is { __kind: 'None' };

/**
 * Option codec for optional values
 * @param itemCodec - Codec for the wrapped value
 * @returns Option codec
 */
function getOptionCodec<T>(
  itemCodec: Codec<T, Uint8Array>
): VariableSizeCodec<Option<T>, Uint8Array>;

/**
 * Nullable codec (null | T)
 * @param itemCodec - Codec for non-null value
 * @returns Nullable codec
 */
function getNullableCodec<T>(
  itemCodec: Codec<T, Uint8Array>
): VariableSizeCodec<T | null, Uint8Array>;

/**
 * Boolean codec
 */
function getBooleanCodec(): FixedSizeCodec<boolean, Uint8Array>;

/**
 * Raw bytes codec
 */
function getBytesCodec(): Codec<Uint8Array, Uint8Array>;

/**
 * Bit array codec
 * @param size - Number of bits
 * @returns Bit array codec
 */
function getBitArrayCodec(size: number): FixedSizeCodec<boolean[], Uint8Array>;

/**
 * Constant value codec
 * @param value - Constant value
 * @returns Constant codec
 */
function getConstantCodec<T>(value: T): FixedSizeCodec<T, Uint8Array>;

/**
 * Unit codec (no data)
 */
function getUnitCodec(): FixedSizeCodec<void, Uint8Array>;

/**
 * Struct codec field configuration
 */
type StructCodecConfig<T> = {
  [K in keyof T]: Codec<T[K], Uint8Array>;
};

/**
 * Tuple codec configuration
 */
type TupleCodecConfig<T extends readonly unknown[]> = {
  [K in keyof T]: Codec<T[K], Uint8Array>;
};

/**
 * Enum variant configuration
 */
type EnumCodecConfig<T> = {
  [K in keyof T]: {
    discriminator?: number;
    codec?: Codec<T[K], Uint8Array>;
  };
};

/**
 * Union variant configuration
 */
type UnionCodecConfig<T> = Array<{
  tag: string | number;
  codec: Codec<T, Uint8Array>;
}>;

/**
 * Codec size information
 */
interface CodecSizeInfo {
  /** Fixed size in bytes, or null if variable */
  size: number | null;
  /** Maximum size for variable codecs */
  maxSize?: number;
  /** Minimum size for variable codecs */
  minSize?: number;
}