1// These types are not exported, and are only used internally 2 3/** 4 * Take in an unknown value and return one that is of type T 5 */ 6type Converter<T> = (object: unknown) => T 7 8type SequenceConverter<T> = (object: unknown) => T[] 9 10type RecordConverter<K extends string, V> = (object: unknown) => Record<K, V> 11 12interface ConvertToIntOpts { 13 clamp?: boolean 14 enforceRange?: boolean 15} 16 17interface WebidlErrors { 18 exception (opts: { header: string, message: string }): TypeError 19 /** 20 * @description Throw an error when conversion from one type to another has failed 21 */ 22 conversionFailed (opts: { 23 prefix: string 24 argument: string 25 types: string[] 26 }): TypeError 27 /** 28 * @description Throw an error when an invalid argument is provided 29 */ 30 invalidArgument (opts: { 31 prefix: string 32 value: string 33 type: string 34 }): TypeError 35} 36 37interface WebidlUtil { 38 /** 39 * @see https://tc39.es/ecma262/#sec-ecmascript-data-types-and-values 40 */ 41 Type (object: unknown): 42 | 'Undefined' 43 | 'Boolean' 44 | 'String' 45 | 'Symbol' 46 | 'Number' 47 | 'BigInt' 48 | 'Null' 49 | 'Object' 50 51 /** 52 * @see https://webidl.spec.whatwg.org/#abstract-opdef-converttoint 53 */ 54 ConvertToInt ( 55 V: unknown, 56 bitLength: number, 57 signedness: 'signed' | 'unsigned', 58 opts?: ConvertToIntOpts 59 ): number 60 61 /** 62 * @see https://webidl.spec.whatwg.org/#abstract-opdef-converttoint 63 */ 64 IntegerPart (N: number): number 65} 66 67interface WebidlConverters { 68 /** 69 * @see https://webidl.spec.whatwg.org/#es-DOMString 70 */ 71 DOMString (V: unknown, opts?: { 72 legacyNullToEmptyString: boolean 73 }): string 74 75 /** 76 * @see https://webidl.spec.whatwg.org/#es-ByteString 77 */ 78 ByteString (V: unknown): string 79 80 /** 81 * @see https://webidl.spec.whatwg.org/#es-USVString 82 */ 83 USVString (V: unknown): string 84 85 /** 86 * @see https://webidl.spec.whatwg.org/#es-boolean 87 */ 88 boolean (V: unknown): boolean 89 90 /** 91 * @see https://webidl.spec.whatwg.org/#es-any 92 */ 93 any <Value>(V: Value): Value 94 95 /** 96 * @see https://webidl.spec.whatwg.org/#es-long-long 97 */ 98 ['long long'] (V: unknown): number 99 100 /** 101 * @see https://webidl.spec.whatwg.org/#es-unsigned-long-long 102 */ 103 ['unsigned long long'] (V: unknown): number 104 105 /** 106 * @see https://webidl.spec.whatwg.org/#es-unsigned-long 107 */ 108 ['unsigned long'] (V: unknown): number 109 110 /** 111 * @see https://webidl.spec.whatwg.org/#es-unsigned-short 112 */ 113 ['unsigned short'] (V: unknown, opts?: ConvertToIntOpts): number 114 115 /** 116 * @see https://webidl.spec.whatwg.org/#idl-ArrayBuffer 117 */ 118 ArrayBuffer (V: unknown): ArrayBufferLike 119 ArrayBuffer (V: unknown, opts: { allowShared: false }): ArrayBuffer 120 121 /** 122 * @see https://webidl.spec.whatwg.org/#es-buffer-source-types 123 */ 124 TypedArray ( 125 V: unknown, 126 TypedArray: NodeJS.TypedArray | ArrayBufferLike 127 ): NodeJS.TypedArray | ArrayBufferLike 128 TypedArray ( 129 V: unknown, 130 TypedArray: NodeJS.TypedArray | ArrayBufferLike, 131 opts?: { allowShared: false } 132 ): NodeJS.TypedArray | ArrayBuffer 133 134 /** 135 * @see https://webidl.spec.whatwg.org/#es-buffer-source-types 136 */ 137 DataView (V: unknown, opts?: { allowShared: boolean }): DataView 138 139 /** 140 * @see https://webidl.spec.whatwg.org/#BufferSource 141 */ 142 BufferSource ( 143 V: unknown, 144 opts?: { allowShared: boolean } 145 ): NodeJS.TypedArray | ArrayBufferLike | DataView 146 147 ['sequence<ByteString>']: SequenceConverter<string> 148 149 ['sequence<sequence<ByteString>>']: SequenceConverter<string[]> 150 151 ['record<ByteString, ByteString>']: RecordConverter<string, string> 152 153 [Key: string]: (...args: any[]) => unknown 154} 155 156export interface Webidl { 157 errors: WebidlErrors 158 util: WebidlUtil 159 converters: WebidlConverters 160 161 /** 162 * @description Performs a brand-check on {@param V} to ensure it is a 163 * {@param cls} object. 164 */ 165 brandCheck <Interface>(V: unknown, cls: Interface, opts?: { strict?: boolean }): asserts V is Interface 166 167 /** 168 * @see https://webidl.spec.whatwg.org/#es-sequence 169 * @description Convert a value, V, to a WebIDL sequence type. 170 */ 171 sequenceConverter <Type>(C: Converter<Type>): SequenceConverter<Type> 172 173 illegalConstructor (): never 174 175 /** 176 * @see https://webidl.spec.whatwg.org/#es-to-record 177 * @description Convert a value, V, to a WebIDL record type. 178 */ 179 recordConverter <K extends string, V>( 180 keyConverter: Converter<K>, 181 valueConverter: Converter<V> 182 ): RecordConverter<K, V> 183 184 /** 185 * Similar to {@link Webidl.brandCheck} but allows skipping the check if third party 186 * interfaces are allowed. 187 */ 188 interfaceConverter <Interface>(cls: Interface): ( 189 V: unknown, 190 opts?: { strict: boolean } 191 ) => asserts V is typeof cls 192 193 // TODO(@KhafraDev): a type could likely be implemented that can infer the return type 194 // from the converters given? 195 /** 196 * Converts a value, V, to a WebIDL dictionary types. Allows limiting which keys are 197 * allowed, values allowed, optional and required keys. Auto converts the value to 198 * a type given a converter. 199 */ 200 dictionaryConverter (converters: { 201 key: string, 202 defaultValue?: unknown, 203 required?: boolean, 204 converter: (...args: unknown[]) => unknown, 205 allowedValues?: unknown[] 206 }[]): (V: unknown) => Record<string, unknown> 207 208 /** 209 * @see https://webidl.spec.whatwg.org/#idl-nullable-type 210 * @description allows a type, V, to be null 211 */ 212 nullableConverter <T>( 213 converter: Converter<T> 214 ): (V: unknown) => ReturnType<typeof converter> | null 215 216 argumentLengthCheck (args: { length: number }, min: number, context: { 217 header: string 218 message?: string 219 }): void 220} 221