primitive.ts

/**
 * This module contains all the primitive types, ready to be composed into more complex codecs.
 * 
 * @module
 */

import type { Codec } from "./codec.ts";

type DataViewFromFunc<T> = (byteOffset: number, littleEndian?: boolean) => T;
type DataViewFromFn<T> = {
    [K in keyof DataView]: DataView[K] extends DataViewFromFunc<T> ? K : never;
}[keyof DataView];

type DataViewToFunc<T> = (byteOffset: number, value: T, littleEndian?: boolean) => void;
type DataViewToFn<T> = {
    [K in keyof DataView]: DataView[K] extends DataViewToFunc<T> ? K : never;
}[keyof DataView];

/**
 * Create a new {@link Codec} that uses {@link DataView} for encoding and decoding data.
 * @param bytes The number of bytes to read.
 * @param fromFn The function in `DataView` to be used for reading value.
 * @param toFn The function in `DataView` to be used for writing value.
 * @param littleEndian Whether the value should be in little endian encoding.
 * @returns A new codec, using underlying `DataView` for encoding and decoding data.
 */
export function dataView<T>(
    bytes: number,
    fromFn: DataViewFromFn<T>,
    toFn: DataViewToFn<T>,
    littleEndian: boolean,
): Codec<T> {
    return {
        encode(v, output) {
            const buf = new ArrayBuffer(bytes);
            (new DataView(buf)[toFn] as DataViewToFunc<T>)(0, v, littleEndian);
            output.write(new Uint8Array(buf));
        },
        decode(input) {
            const raw = input.read(bytes);
            return (new DataView(raw.buffer)[fromFn] as DataViewFromFunc<T>)(0, littleEndian);
        },
    };
}

/**
 * A {@link Codec} for `number` values that are 8-bit unsigned integers.
 */
export const u8: Codec<number> = {
    encode: (v, output) => output.write([v]),
    decode: (input) => input.read(1)[0],
};

/**
 * A {@link Codec} for `number` values that are 8-bit signed integers.
 */
export const i8: Codec<number> = {
    encode: (v, output) => output.write([v]),
    decode: (input) => input.read(1, Int8Array)[0],
};

/** A {@link Codec} for `number` values that are 16-bit unsigned integers in big endian format. */
export const u16BE: Codec<number> = dataView(2, "getUint16", "setUint16", false);

/**A {@link Codec} for `number` values that are 32-bit unsigned integers in big endian format. */
export const u32BE: Codec<number> = dataView(4, "getUint32", "setUint32", false);

/**A {@link Codec} for `bigint` values that are 64-bit unsigned integers in big endian format. */
export const u64BE: Codec<bigint> = dataView(8, "getBigUint64", "setBigUint64", false);

/**A {@link Codec} for `number` values that are 16-bit signed integers in big endian format. */
export const i16BE: Codec<number> = dataView(2, "getInt16", "setInt16", false);

/**A {@link Codec} for `number` values that are 32-bit signed integers in big endian format. */
export const i32BE: Codec<number> = dataView(4, "getInt32", "setInt32", false);

/**A {@link Codec} for `bigint` values that are 64-bit signed integers in big endian format. */
export const i64BE: Codec<bigint> = dataView(8, "getBigInt64", "setBigInt64", false);

/**A {@link Codec} for `number` values that are 16-bit floating-point numbers in big endian format. */
export const f16BE: Codec<number> = dataView(2, "getFloat16", "setFloat16", false);

/**A {@link Codec} for `number` values that are 32-bit floating-point numbers in big endian format. */
export const f32BE: Codec<number> = dataView(4, "getFloat32", "setFloat32", false);

/** A {@link Codec} for `number` values that are 64-bit floating-point numbers in big endian format. */
export const f64BE: Codec<number> = dataView(8, "getFloat64", "setFloat64", false);

/** A {@link Codec} for `number` values that are 16-bit unsigned integers in little endian format. */
export const u16LE: Codec<number> = dataView(2, "getUint16", "setUint16", true);

/** A {@link Codec} for `number` values that are 32-bit unsigned integers in little endian format. */
export const u32LE: Codec<number> = dataView(4, "getUint32", "setUint32", true);

/** A {@link Codec} for `bigint` values that are 64-bit unsigned integers in little endian format. */
export const u64LE: Codec<bigint> = dataView(8, "getBigUint64", "setBigUint64", true);

/** A {@link Codec} for `number` values that are 16-bit signed integers in little endian format. */
export const i16LE: Codec<number> = dataView(2, "getInt16", "setInt16", true);

/** A {@link Codec} for `number` values that are 32-bit signed integers in little endian format. */
export const i32LE: Codec<number> = dataView(4, "getInt32", "setInt32", true);

/** A {@link Codec} for `bigint` values that are 64-bit signed integers in little endian format. */
export const i64LE: Codec<bigint> = dataView(8, "getBigInt64", "setBigInt64", true);

/** A {@link Codec} for `number` values that are 16-bit floating-point numbers in little endian format. */
export const f16LE: Codec<number> = dataView(2, "getFloat16", "setFloat16", true);

/** A {@link Codec} for `number` values that are 32-bit floating-point numbers in little endian format. */
export const f32LE: Codec<number> = dataView(4, "getFloat32", "setFloat32", true);

/** A {@link Codec} for `number` values that are 64-bit floating-point numbers in little endian format. */
export const f64LE: Codec<number> = dataView(8, "getFloat64", "setFloat64", true);

/**
 * A {@link Codec} that encodes `0x01` for `true` and `0x00` for `false`.
 */
export const bool: Codec<boolean> = {
    encode: (obj, output) => output.write([obj ? 1 : 0]),
    decode: (input) => !!input.read(1)[0],
};

/**
 * A {@link Codec} that encodes variable-length integer in little endian format. Since the binary operation on JS number
 * are always limited to 32-bit, this codec is not suitable for any value outside `2**31 - 1` limit.
 */
export const uvarLE: Codec<number> = {
    encode(v, output) {
        if (v < 0) throw new Error(`Must be a non-negative integer, found ${v}`);
        if (v >= 0x80000000) throw new Error(
            `Value ${v} is greater than 0x80000000, which when applied binary op, will become negative value`
        );

        const out = new Uint8Array(5); // At most 5 bytes, since binary op on JS is limited to 32-bit
        let i = 0;

        do {
            const b = v & 0x7F;
            v >>= 7;
            out[i++] = b | (v != 0 ? 0x80 : 0);
        } while (v != 0);

        output.write(out.subarray(0, i));
    },
    decode(input) {
        let v = 0;
        let i = 0;
        let b: number;

        do {
            if (i >= 5) throw new Error(`Varint overflow (expecting at most 4 consecutive bytes with next marker)`);
            [b] = input.read(1);
            v |= (b & 0x7F) << (7 * i);
            i++;
        } while (b & 0x80);

        return v;
    },
};

/**
 * Create a new {@link Codec} for encoding and decoding between `string` and UTF-8 with fixed number of bytes. If the
 * length of encoded UTF-8 is less than maximum bytes, the data will suffixed with zeros.
 * @param bytes The maximum number of bytes.
 * @returns A new codec that can encode and decode UTF-8 strings.
 */
export function fixedUtf8(bytes: number): Codec<string> {
    const encoder = new TextEncoder();
    const decoder = new TextDecoder();

    return {
        encode(obj, output) {
            const str = encoder.encode(obj);

            if (str.length > bytes) {
                throw new Error(
                    `Exceeding bytes limit (encoded UTF-8 length must <= ${bytes} bytes, found ${str.length})`,
                );
            }

            output.write(str);
            output.write(new Uint8Array(bytes - str.length));
        },
        decode(input) {
            const buf = input.read(bytes);
            const idx = buf.indexOf(0);
            return decoder.decode(idx != -1 ? buf.subarray(0, idx) : buf);
        },
    };
}

/**
 * Create a new {@link Codec} for encoding and decoding between `string` and length-prefixed UTF-8.
 * @param lengthCodec The codec for encoding and decoding length of UTF-8 data.
 * @returns A new codec that can encode and decode UTF-8 strings.
 */
export function dynamicUtf8(lengthCodec: Codec<number>): Codec<string> {
    const encoder = new TextEncoder();
    const decoder = new TextDecoder();

    return {
        encode(obj, output) {
            const str = encoder.encode(obj);
            lengthCodec.encode(str.length, output);
            output.write(str);
        },
        decode(input) {
            const bytes = lengthCodec.decode(input);
            return decoder.decode(input.read(bytes));
        },
    };
}