import { type PrimativeKey } from '../key';
import { type FactoryWithRequiredInput } from '../getter/getter';
import { type Maybe } from '../value/maybe.type';
/**
 * Map object of PrimativeKey dencoder values, keyed by the encoded value.
 */
export type PrimativeKeyDencoderValueMap<D extends PrimativeKey, E extends PrimativeKey> = {
    [key in E]: D;
};
/**
 * A tuple pairing an encoded value to its decoded counterpart.
 */
export type PrimativeKeyDencoderTuple<D extends PrimativeKey, E extends PrimativeKey> = [E, D];
/**
 * An array of {@link PrimativeKeyDencoderTuple} values.
 */
export type PrimativeKeyDencoderTupleArray<D extends PrimativeKey, E extends PrimativeKey> = PrimativeKeyDencoderTuple<D, E>[];
/**
 * PrimativeKeyDencoder values. No key or value should be repeated.
 */
export type PrimativeKeyDencoderValues<D extends PrimativeKey, E extends PrimativeKey> = PrimativeKeyDencoderTupleArray<D, E> | PrimativeKeyDencoderValueMap<D, E>;
/**
 * A bidirectional Map that maps both encoded-to-decoded and decoded-to-encoded values.
 * Also carries the original tuple array used to construct it.
 */
export type PrimativeKeyDencoderMap<D extends PrimativeKey, E extends PrimativeKey> = Map<D | E, E | D> & {
    readonly _tuples: PrimativeKeyDencoderTupleArray<D, E>;
};
/**
 * Creates a bidirectional {@link PrimativeKeyDencoderMap} from the given values,
 * allowing lookup in both directions (encoded-to-decoded and decoded-to-encoded).
 *
 * @param values - encoder/decoder value pairs as tuples or a map object
 * @returns a bidirectional Map for encoding/decoding
 * @throws Error if any key or value is repeated
 */
export declare function primativeKeyDencoderMap<D extends PrimativeKey, E extends PrimativeKey>(values: PrimativeKeyDencoderValues<D, E>): PrimativeKeyDencoderMap<D, E>;
/**
 * Configuration for creating a {@link PrimativeKeyDencoderFunction}.
 */
export interface PrimativeKeyDencoderConfig<D extends PrimativeKey, E extends PrimativeKey> {
    /**
     * The encode/decode value pairs.
     */
    readonly values: PrimativeKeyDencoderValues<D, E>;
    /**
     * Optional factory to produce a fallback value when a lookup misses.
     * If not provided or if it returns null, an error is thrown for unknown values.
     */
    readonly defaultValue?: FactoryWithRequiredInput<D | E, D | E>;
}
/**
 * Used for encoding/decoding pre-configured strings values from a map.
 *
 * If a single value is input that produces a nullish value, an error is thrown.
 */
export type PrimativeKeyDencoderFunction<D extends PrimativeKey, E extends PrimativeKey> = ((encodedValue: E) => D) & ((decodedValue: D) => E) & ((encodedValues: E[]) => D[]) & ((decodedValues: D[]) => E[]) & {
    readonly _map: PrimativeKeyDencoderMap<D, E>;
};
/**
 * Default fallback factory for {@link PrimativeKeyDencoderFunction} that always returns null,
 * causing an error to be thrown for unknown values.
 *
 * @param _input - the unknown value to look up (ignored; always returns null)
 * @returns always returns null to signal an unknown value
 */
export declare const PRIMATIVE_KEY_DENCODER_VALUE: (_input: unknown) => null;
/**
 * Creates a new {@link PrimativeKeyDencoderFunction} that can bidirectionally encode/decode
 * primitive key values based on the configured value pairs.
 *
 * @param config - configuration with value pairs and optional default fallback
 * @returns a function that encodes or decodes single values or arrays
 * @throws Error if a single value lookup produces a null result and no default handles it
 */
export declare function primativeKeyDencoder<D extends PrimativeKey, E extends PrimativeKey>(config: PrimativeKeyDencoderConfig<D, E>): PrimativeKeyDencoderFunction<D, E>;
/**
 * Configuration for creating a {@link PrimativeKeyStringDencoderFunction} that can encode/decode
 * between a compact string representation and an array of values.
 */
export interface PrimativeKeyStringDencoderConfig<D extends PrimativeKey, E extends PrimativeKey> {
    /**
     * Dencoder to use, or config to create one.
     */
    readonly dencoder: PrimativeKeyDencoderConfig<D, E> | PrimativeKeyDencoderFunction<D, E>;
    /**
     * Splitter value. If not defined then the max size of the "encoded" values must be 1 character.
     */
    readonly splitter?: string;
}
/**
 * Maps the input encode/decode value to the proper value.
 *
 * If a single value is input that produces a nullish value, an error is thrown.
 */
export type PrimativeKeyStringDencoderFunction<D extends PrimativeKey, E extends PrimativeKey, S extends string = string> = ((encodedValues: S) => (E | D)[]) & ((decodedValues: (E | D)[]) => S);
/**
 * Creates a new {@link PrimativeKeyStringDencoderFunction} that converts between a compact string
 * and an array of encoded/decoded values.
 *
 * When no splitter is defined, all encoded values must be exactly one character long so the string
 * can be split character-by-character.
 *
 * @param config - configuration with dencoder and optional splitter
 * @returns a bidirectional function for string-to-array and array-to-string conversion
 * @throws Error if encoded values contain the splitter character, or if values exceed one character when no splitter is defined
 */
export declare function primativeKeyStringDencoder<D extends PrimativeKey, E extends PrimativeKey>(config: PrimativeKeyStringDencoderConfig<D, E>): PrimativeKeyStringDencoderFunction<D, E>;
/**
 * An encodable number. This is typically a positive integer value.
 */
export type NumberStringDencoderNumber = number;
/**
 * A number-encoded string. Little-Endian. Should Decode to the same value each time.
 */
export type NumberStringDencoderString = string;
/**
 * Digits used when encoding/decoding a value.
 *
 * The number of digits/characters must be a factor of 2. I.E. 8, 16, 32, 64
 */
export type NumberStringDencoderDigits = string;
/**
 * The number of "bits" given by the NumberStringDencoderDigits.
 */
export type NumberStringDencoderBitDepth = 2 | 4 | 8 | 16 | 32 | 64;
/**
 * Default 64 NumberStringDencoderDigits value.
 */
export declare const NUMBER_STRING_DENCODER_64_DIGITS: NumberStringDencoderDigits;
/**
 * The default negative prefix for negative numbers.
 */
export declare const NUMBER_STRING_DENCODER_64_DEFAULT_NEGATIVE_PREFIX = "!";
/**
 * The NumberString dencoder type
 * - positive_integer: can only encode/decode positive integers
 * - integer: can only encode/decode integers
 * - positive_decimal: can encoded/decode positive decimals
 * - decimal: can encoded/decode decimals
 */
export type NumberStringDencoderType = 'positive_integer' | 'integer' | 'positive_decimal' | 'decimal';
/**
 * A NumberString dencoder.
 *
 * Can encode/decode a number from the input string.
 */
export interface NumberStringDencoder {
    readonly type: NumberStringDencoderType;
    readonly digits: NumberStringDencoderDigits;
    readonly bitDepth: NumberStringDencoderBitDepth;
    readonly negativePrefix?: Maybe<string>;
    /**
     * Encodes the input number to the corresponding NumberStringDencoderString.
     *
     * @param number
     */
    encodeNumber(number: NumberStringDencoderNumber): NumberStringDencoderString;
    /**
     * Decodes the input number to the corresponding NumberStringDencoderNumber.
     *
     * @param encodedNumber
     */
    decodeNumber(encodedNumber: NumberStringDencoderString): NumberStringDencoderNumber;
}
/**
 * Configuration for creating a {@link NumberStringDencoder}.
 */
export interface NumberStringDencoderConfig {
    /**
     * Optional negative prefix character. Should not be in the digits.
     */
    readonly negativePrefix?: Maybe<string>;
    /**
     * The character set used for encoding. Length must be a power of 2.
     */
    readonly digits: NumberStringDencoderDigits;
}
/**
 * Creates an integer-type {@link NumberStringDencoder} that can encode and decode integers
 * using a custom character set (digit alphabet).
 *
 * If the config does not include a negative prefix, negative numbers lose their sign during encoding.
 *
 * @param config - configuration with digit alphabet and optional negative prefix
 * @returns a NumberStringDencoder capable of encoding/decoding integers
 */
export declare function numberStringDencoder(config: NumberStringDencoderConfig): NumberStringDencoder;
/**
 * Pre-configured 64-character {@link NumberStringDencoder} using the default digit alphabet and negative prefix.
 */
export declare const NUMBER_STRING_DENCODER_64: NumberStringDencoder;
/**
 * A bidirectional function that encodes a number to a string or decodes a string to a number,
 * depending on the type of the input.
 */
export type NumberStringDencoderFunction = ((input: NumberStringDencoderString) => NumberStringDencoderNumber) & ((input: NumberStringDencoderNumber) => NumberStringDencoderString);
/**
 * Creates a {@link NumberStringDencoderFunction} from the given dencoder.
 * The returned function auto-detects the input type: numbers are encoded, strings are decoded.
 *
 * @param dencoder - the NumberStringDencoder to wrap
 * @returns a bidirectional encode/decode function
 */
export declare function numberStringDencoderFunction(dencoder: NumberStringDencoder): NumberStringDencoderFunction;
/**
 * Creates a function that always returns the encoded string form of the input.
 * Numbers are encoded; strings are passed through as-is.
 *
 * @param dencoder - the NumberStringDencoder to use for encoding
 * @returns a function that normalizes input to an encoded string
 */
export declare function numberStringDencoderEncodedStringValueFunction(dencoder: NumberStringDencoder): (input: NumberStringDencoderString | NumberStringDencoderNumber) => NumberStringDencoderString;
/**
 * Creates a function that always returns the decoded number form of the input.
 * Strings are decoded; numbers are passed through as-is.
 *
 * @param dencoder - the NumberStringDencoder to use for decoding
 * @returns a function that normalizes input to a decoded number
 */
export declare function numberStringDencoderDecodedNumberValueFunction(dencoder: NumberStringDencoder): (input: NumberStringDencoderString | NumberStringDencoderNumber) => NumberStringDencoderNumber;