/**
 * Type definitions for the packet parsing library.
 */

/**
 * Enumeration of supported field types for dissecting packets.
 *
 * Each field type corresponds to a specific way of interpreting bytes in a packet, such as boolean
 * values, integers of various sizes and endianness, floating point numbers, date/time values, and
 * array buffers for strings and byte arrays.
 */
export const FieldType = {
  // Boolean types
  BOOL: "BOOL", // Boolean value (stored as a byte, 0 for false, non-zero for true)

  // Number types
  BITS: "BITS", // 1-bit values stored in a number (1 bit per value, packed into bytes)
  CHAR: "CHAR", // 8-bit character (1 byte)
  INT8: "INT8", // 8-bit signed integer (1 byte)
  INT16_LE: "INT16_LE", // 16-bit signed integer (little-endian)
  INT16_BE: "INT16_BE", // 16-bit signed integer (big-endian)
  INT32_LE: "INT32_LE", // 32-bit signed integer (little-endian)
  INT32_BE: "INT32_BE", // 32-bit signed integer (big-endian)
  INT64_LE: "INT64_LE", // 64-bit signed integer (little-endian)
  INT64_BE: "INT64_BE", // 64-bit signed integer (big-endian)
  UINT8: "UINT8", // 8-bit unsigned integer
  UINT16_LE: "UINT16_LE", // 16-bit unsigned integer (little-endian)
  UINT16_BE: "UINT16_BE", // 16-bit unsigned integer (big-endian)
  UINT32_LE: "UINT32_LE", // 32-bit unsigned integer (little-endian)
  UINT32_BE: "UINT32_BE", // 32-bit unsigned integer (big-endian)
  UINT64_LE: "UINT64_LE", // 64-bit unsigned integer (little-endian)
  UINT64_BE: "UINT64_BE", // 64-bit unsigned integer (big-endian)
  FLOAT32_LE: "FLOAT32_LE", // 32-bit IEEE floating point (little-endian)
  FLOAT32_BE: "FLOAT32_BE", // 32-bit IEEE floating point (big-endian)
  FLOAT64_LE: "FLOAT64_LE", // 64-bit IEEE floating point (little-endian)
  FLOAT64_BE: "FLOAT64_BE", // 64-bit IEEE floating point (big-endian)
  VARINT: "VARINT", // Variable-length integer (unsigned, LEB128 encoding)
  VARSINT: "VARSINT", // Variable-length integer (signed, LEB128 encoding)

  // Date/time types (stored as integer timestamps)
  DATE32_LE: "DATE32_LE", // 32-bit integer date (e.g., seconds since epoch) little-endian
  DATE32_BE: "DATE32_BE", // 32-bit integer date big-endian
  DATE64_LE: "DATE64_LE", // 64-bit integer date (e.g., ms since epoch) little-endian
  DATE64_BE: "DATE64_BE", // 64-bit integer date big-endian

  // Array buffer types
  BYTES: "BYTES", // 8-bits per value array (Uint8Array)
  C_STRING: "C_STRING", // Null-terminated string (C-style) (Uint8Array)
  UTF8_STRING: "UTF8_STRING", // UTF-8 encoded string (Uint8Array)
  WORDS: "WORDS", // 16-bits per value array (Uint16Array)
  DWORDS: "DWORDS", // 32-bits per value array (Uint32Array)
  QWORDS: "QWORDS", // 64-bits per value array (BigUint64Array)

  // Aliases
  FLAG: "BOOL", // alternate name for boolean/flag fields
  STRING: "UTF8_STRING" // alias for UTF8 encoded strings
} as const;

export type FieldType = (typeof FieldType)[keyof typeof FieldType];

/**
 * Interface for a packet, which can be dissected into segments and fields. This is a placeholder
 * for any additional properties or methods that may be needed for representing a packet in the future.
 */
export interface Packet {
  data: string | Uint8Array | ArrayBuffer; // Raw packet data as an ArrayBuffer
  snr?: number; // Optional signal-to-noise ratio (for radio packets)
  rssi?: number; // Optional received signal strength indicator (for radio packets)
  parsed?: unknown; // Optional parsed representation of the packet (e.g., a structured object)
  dissected?: Dissected; // Optional dissected representation of the packet (array of segments)

  /**
   * Method to dissect the packet into segments and fields, returning an array of segments.
   *
   * This method can be implemented by classes that represent specific packet types, and can
   * use the defined field types to parse the raw data into a structured format.
   */
  dissect?(): Dissected; // Method to dissect the packet into segments and fields
}

/**
 * Interface for a protocol, which defines how to encode and decode packets. This can be used to
 * represent different radio protocols (e.g., AX.25, LoRaWAN) and their specific encoding/decoding
 * logic.
 */
export interface Protocol {
  // Name of the protocol (e.g., "AX.25", "LoRaWAN", etc.)
  name: string;

  // Method to encode a packet into an ArrayBuffer (for serialization)
  encode: (packet: Packet) => ArrayBuffer;

  // Method to decode a packet into a dissected representation (array of segments)
  decode: (data: ArrayBuffer, dissect?: boolean) => Packet;

  // Method to return a string representation of the protocol (e.g., for debugging or logging)
  toString(): string;
}

/**
 * Represents a dissected packet, which is an array of segments.
 */
export type Dissected = Segment[];

/**
 * Represents a segment of bytes in a packet, defined by a name and an array of fields.
 * Each field specifies the type and length of data it represents.
 */
export interface Segment {
  name: string;
  data?: ArrayBuffer; // Optional raw data for the segment (if needed for parsing / serialization)
  isString?: boolean; // Optional flag indicating if the segment represents a string (for special handling)
  fields: Field[];
}

/**
 * Represents a field within a segment, defined by its type, name, and optional properties
 * for bit fields and array lengths.
 */
export interface Field {
  type: FieldType;
  name: string;
  data?: ArrayBuffer; // Optional raw data for the field (if needed for parsing / serialization)
  value?: unknown; // Optional value for the field (used for serialization or as a default value)
  bits?: BitField[]; // Optional array of bit field definitions (for BITS type)
  length?: number; // Optional length for array types (e.g., BYTES, WORDS)
}

/**
 * Represents a bit field definition, specifying the name and size of the field in bits,
 * and an optional flag indicating if it is the least significant bit in a byte (for BITS type).
 */
export interface BitField {
  name: string;
  size: number; // Number of bits for this field (must be > 0)
  lsb?: boolean; // Optional flag indicating if this field is the least significant bit in the byte (for BITS type)
}