webidl.d.ts

// These types are not exported, and are only used internally

/**
 * Take in an unknown value and return one that is of type T
 */
type Converter<T> = (object: unknown) => T

type SequenceConverter<T> = (object: unknown) => T[]

type RecordConverter<K extends string, V> = (object: unknown) => Record<K, V>

interface ConvertToIntOpts {
  clamp?: boolean
  enforceRange?: boolean
}

interface WebidlErrors {
  exception (opts: { header: string, message: string }): TypeError
  /**
   * @description Throw an error when conversion from one type to another has failed
   */
  conversionFailed (opts: {
    prefix: string
    argument: string
    types: string[]
  }): TypeError
  /**
   * @description Throw an error when an invalid argument is provided
   */
  invalidArgument (opts: {
    prefix: string
    value: string
    type: string
  }): TypeError
}

interface WebidlUtil {
  /**
   * @see https://tc39.es/ecma262/#sec-ecmascript-data-types-and-values
   */
  Type (object: unknown):
    | 'Undefined'
    | 'Boolean'
    | 'String'
    | 'Symbol'
    | 'Number'
    | 'BigInt'
    | 'Null'
    | 'Object'

  /**
   * @see https://webidl.spec.whatwg.org/#abstract-opdef-converttoint
   */
  ConvertToInt (
    V: unknown,
    bitLength: number,
    signedness: 'signed' | 'unsigned',
    opts?: ConvertToIntOpts
  ): number

  /**
   * @see https://webidl.spec.whatwg.org/#abstract-opdef-converttoint
   */
  IntegerPart (N: number): number
}

interface WebidlConverters {
  /**
   * @see https://webidl.spec.whatwg.org/#es-DOMString
   */
  DOMString (V: unknown, opts?: {
    legacyNullToEmptyString: boolean
  }): string

  /**
   * @see https://webidl.spec.whatwg.org/#es-ByteString
   */
  ByteString (V: unknown): string

  /**
   * @see https://webidl.spec.whatwg.org/#es-USVString
   */
  USVString (V: unknown): string

  /**
   * @see https://webidl.spec.whatwg.org/#es-boolean
   */
  boolean (V: unknown): boolean

  /**
   * @see https://webidl.spec.whatwg.org/#es-any
   */
  any <Value>(V: Value): Value

  /**
   * @see https://webidl.spec.whatwg.org/#es-long-long
   */
  ['long long'] (V: unknown): number

  /**
   * @see https://webidl.spec.whatwg.org/#es-unsigned-long-long
   */
  ['unsigned long long'] (V: unknown): number

  /**
   * @see https://webidl.spec.whatwg.org/#es-unsigned-short
   */
  ['unsigned short'] (V: unknown): number

  /**
   * @see https://webidl.spec.whatwg.org/#idl-ArrayBuffer
   */
  ArrayBuffer (V: unknown): ArrayBufferLike
  ArrayBuffer (V: unknown, opts: { allowShared: false }): ArrayBuffer

  /**
   * @see https://webidl.spec.whatwg.org/#es-buffer-source-types
   */
  TypedArray (
    V: unknown,
    TypedArray: NodeJS.TypedArray | ArrayBufferLike
  ): NodeJS.TypedArray | ArrayBufferLike
  TypedArray (
    V: unknown,
    TypedArray: NodeJS.TypedArray | ArrayBufferLike,
    opts?: { allowShared: false }
  ): NodeJS.TypedArray | ArrayBuffer

  /**
   * @see https://webidl.spec.whatwg.org/#es-buffer-source-types
   */
  DataView (V: unknown, opts?: { allowShared: boolean }): DataView

  /**
   * @see https://webidl.spec.whatwg.org/#BufferSource
   */
  BufferSource (
    V: unknown,
    opts?: { allowShared: boolean }
  ): NodeJS.TypedArray | ArrayBufferLike | DataView

  ['sequence<ByteString>']: SequenceConverter<string>
  
  ['sequence<sequence<ByteString>>']: SequenceConverter<string[]>

  ['record<ByteString, ByteString>']: RecordConverter<string, string>

  [Key: string]: (...args: any[]) => unknown
}

export interface Webidl {
  errors: WebidlErrors
  util: WebidlUtil
  converters: WebidlConverters

  /**
   * @description Performs a brand-check on {@param V} to ensure it is a
   * {@param cls} object.
   */
  brandCheck <Interface>(V: unknown, cls: Interface): asserts V is Interface

  /**
   * @see https://webidl.spec.whatwg.org/#es-sequence
   * @description Convert a value, V, to a WebIDL sequence type.
   */
  sequenceConverter <Type>(C: Converter<Type>): SequenceConverter<Type>

  /**
   * @see https://webidl.spec.whatwg.org/#es-to-record
   * @description Convert a value, V, to a WebIDL record type.
   */
  recordConverter <K extends string, V>(
    keyConverter: Converter<K>,
    valueConverter: Converter<V>
  ): RecordConverter<K, V>

  /**
   * Similar to {@link Webidl.brandCheck} but allows skipping the check if third party
   * interfaces are allowed.
   */
  interfaceConverter <Interface>(cls: Interface): (
    V: unknown,
    opts?: { strict: boolean }
  ) => asserts V is typeof cls

  // TODO(@KhafraDev): a type could likely be implemented that can infer the return type
  // from the converters given?
  /**
   * Converts a value, V, to a WebIDL dictionary types. Allows limiting which keys are
   * allowed, values allowed, optional and required keys. Auto converts the value to
   * a type given a converter.
   */
  dictionaryConverter (converters: {
    key: string,
    defaultValue?: unknown,
    required?: boolean,
    converter: (...args: unknown[]) => unknown,
    allowedValues?: unknown[]
  }[]): (V: unknown) => Record<string, unknown>

  /**
   * @see https://webidl.spec.whatwg.org/#idl-nullable-type
   * @description allows a type, V, to be null
   */
  nullableConverter <T>(
    converter: Converter<T>
  ): (V: unknown) => ReturnType<typeof converter> | null

  argumentLengthCheck (args: { length: number }, min: number, context: {
    header: string
    message?: string
  }): void
}