@types/webidl2/index.d.ts

TypeScript definitions for webidl2

export as namespace WebIDL2;
export {};

export function parse(str: string, options?: ParseOptions): IDLRootType[];
export function write(ast: IDLRootType[], options?: WriteOptions): string;
export function validate(ast: IDLRootType[]): WebIDLErrorData[];

export type IDLRootType =
    | CallbackType
    | CallbackInterfaceType
    | DictionaryType
    | EnumType
    | IncludesType
    | InterfaceMixinType
    | InterfaceType
    | NamespaceType
    | TypedefType;

export type IDLCallbackInterfaceMemberType = ConstantMemberType | OperationMemberType;

export type IDLInterfaceMemberType =
    | AttributeMemberType
    | ConstantMemberType
    | ConstructorMemberType
    | DeclarationMemberType
    | OperationMemberType;

export type IDLInterfaceMixinMemberType = AttributeMemberType | ConstantMemberType | OperationMemberType;

export type IDLNamespaceMemberType = AttributeMemberType | OperationMemberType;

export type IDLTypeDescription = GenericTypeDescription | SingleTypeDescription | UnionTypeDescription;

export interface ParseOptions {
    /** Boolean indicating whether the result should include EOF node or not. */
    concrete?: boolean | undefined;
    /** The source name, typically a filename. Errors and validation objects can indicate their origin if you pass a value. */
    sourceName?: string | undefined;
}

export interface WriteOptions {
    templates?: {
        /**
         * A function that receives syntax strings plus anything the templates returned.
         * The items are guaranteed to be ordered.
         * The returned value may be again passed to any template functions,
         * or it may also be the final return value of `write()`.
         * @param items
         */
        wrap?(items: any[]): any;
        /**
         * @param t A trivia string, which includes whitespaces and comments.
         */
        trivia?(t: string): string;
        /**
         * The identifier for a container type. For example, the `Foo` part of `interface Foo {};`.
         * @param escaped The escaped raw name of the definition.
         * @param data The definition with the name
         * @param parent The parent of the definition, undefined if absent
         */
        name?(escaped: string, { data, parent }: { data: any; parent: any }): string;
        /**
         * Called for each type referece, e.g. `Window`, `DOMString`, or `unsigned long`.
         * @param escaped The referenced name. Typically string, but may also be the return
         *            value of `wrap()` if the name contains whitespace.
         * @param unescaped Unescaped reference.
         */
        reference?(escaped: any, unescaped: any): any;
        /**
         * Called for each generic-form syntax, e.g. `sequence`, `Promise`, or `maplike`.
         * @param name The keyword for syntax
         */
        generic?(name: string): string;
        /**
         * Called for each nameless members, e.g. `stringifier` for `stringifier;` and `constructor` for `constructor();`
         * @param keyword The keyword for syntax
         */
        nameless?(keyword: string, { data, parent }: { data: any; parent: any }): string;
        /**
         * Called only once for each types, e.g. `Document`, `Promise<DOMString>`, or `sequence<long>`.
         * @param type The `wrap()`ed result of references and syntatic bracket strings.
         */
        type?(type: any): any;
        /**
         * Receives the return value of `reference()`. String if it's absent.
         */
        inheritance?(inh: any): any;
        /**
         * Called for each IDL type definition, e.g. an interface, an operation, or a typedef.
         * @param content The wrapped value of everything the definition contains.
         * @param data The original definition object
         * @param parent The parent of the definition, undefined if absent
         */
        definition?(content: any, { data, parent }: { data: any; parent: any }): any;
        /**
         * Called for each extended attribute annotation.
         * @param content The wrapped value of everything the annotation contains.
         */
        extendedAttribute?(content: any): any;
        /**
         * The `Foo` part of `[Foo=Whatever]`.
         * @param ref The name of the referenced extended attribute name.
         */
        extendedAttributeReference?(ref: any): any;
    };
}

export class WebIDLError extends Error {
    /** the error message */
    message: string;
    bareMessage: string;

    /** the line at which the error occurred. */
    context: string;
    line: number;
    sourceName: string | undefined;

    /** a short peek at the text at the point where the error happened */
    input: string;
    /** the five tokens at the point of error, as understood by the tokeniser */
    tokens: Token[];
}

export class WebIDLParseError extends WebIDLError {
    constructor(options: {
        message: string;
        bareMessage: string;
        context: string;
        line: number;
        sourceName?: string | undefined;
        input: string;
        tokens: Token[];
    });

    name: "WebIDLParseError";
}

export class WebIDLErrorData extends WebIDLError {
    /** the level of error */
    level: "error" | "warning";

    /** A function to automatically fix the error */
    autofix?(): void;

    /** The name of the rule that threw the error */
    ruleName: string;
}

export interface Token {
    type: string;
    value: string;
    trivia: string;
    line: number;
    index: number;
}

export interface AbstractBase {
    /** String indicating the type of this node. */
    type: string | null;
    /** The container of this type. */
    parent: AbstractBase | null;
    /** A list of extended attributes. */
    extAttrs: ExtendedAttribute[];
}

export interface AbstractTypeDescription extends AbstractBase {
    /** Boolean indicating whether this is nullable or not. */
    nullable: boolean;
    /** The container of this type. */
    parent:
        | Argument
        | AttributeMemberType
        | CallbackType
        | ConstantMemberType
        | DeclarationMemberType
        | FieldType
        | OperationMemberType
        | TypedefType
        | UnionTypeDescription;
}

interface AbstractNonUnionTypeDescription extends AbstractTypeDescription {
    /** String indicating the generic type (e.g. "Promise", "sequence"). The empty string otherwise. */
    generic: IDLTypeDescription["generic"];
    /** Boolean indicating whether this is a union type or not. */
    union: false;
}

interface AbstractGenericTypeDescription extends AbstractNonUnionTypeDescription {
    /**
     * Contains the IDL type description for the type in the sequence,
     * the eventual value of the promise, etc.
     */
    idlType: IDLTypeDescription[];
}

export type GenericTypeDescription =
    | FrozenArrayTypeDescription
    | ObservableArrayTypeDescription
    | PromiseTypeDescription
    | RecordTypeDescription
    | SequenceTypeDescription;

export interface FrozenArrayTypeDescription extends AbstractGenericTypeDescription {
    generic: "FrozenArray";
    idlType: [IDLTypeDescription];
}

export interface ObservableArrayTypeDescription extends AbstractGenericTypeDescription {
    generic: "ObservableArray";
    idlType: [IDLTypeDescription];
}

export interface PromiseTypeDescription extends AbstractGenericTypeDescription {
    generic: "Promise";
    idlType: [IDLTypeDescription];
}

export interface RecordTypeDescription extends AbstractGenericTypeDescription {
    generic: "record";
    idlType: [IDLTypeDescription, IDLTypeDescription];
}

export interface SequenceTypeDescription extends AbstractGenericTypeDescription {
    generic: "sequence";
    idlType: [IDLTypeDescription];
}

export interface SingleTypeDescription extends AbstractNonUnionTypeDescription {
    generic: "";
    /**
     * In most cases, this will just be a string with the type name.
     * If the type is a union, then this contains an array of the types it unites.
     * If it is a generic type, it contains the IDL type description for the type in the sequence,
     * the eventual value of the promise, etc.
     */
    idlType: string;
}

export interface UnionTypeDescription extends AbstractTypeDescription {
    /** String indicating the generic type (e.g. "Promise", "sequence"). The empty string otherwise. */
    generic: "";
    /** Boolean indicating whether this is a union type or not. */
    union: true;
    /**
     * In most cases, this will just be a string with the type name.
     * If the type is a union, then this contains an array of the types it unites.
     * If it is a generic type, it contains the IDL type description for the type in the sequence,
     * the eventual value of the promise, etc.
     */
    idlType: IDLTypeDescription[];
}

export interface AbstractContainer extends AbstractBase {
    /** The name of the container. */
    name: string;
    /** A boolean indicating whether this container is partial. */
    partial: boolean;
    /** An array of container members (attributes, operations, etc.). Empty if there are none. */
    members: AbstractBase[];
}

export interface CallbackInterfaceType extends AbstractContainer {
    type: "callback interface";
    members: IDLCallbackInterfaceMemberType[];
    inheritance: null;
    parent: null;
}

export interface InterfaceType extends AbstractContainer {
    type: "interface";
    members: IDLInterfaceMemberType[];
    /** A string giving the name of an interface this one inherits from, null otherwise. */
    inheritance: string | null;
    parent: null;
}

export interface InterfaceMixinType extends AbstractContainer {
    type: "interface mixin";
    members: IDLInterfaceMixinMemberType[];
    inheritance: null;
    parent: null;
}

export interface NamespaceType extends AbstractContainer {
    type: "namespace";
    members: IDLNamespaceMemberType[];
    inheritance: null;
    parent: null;
}

export interface CallbackType extends AbstractBase {
    type: "callback";
    /** The name of the callback. */
    name: string;
    /** An IDL Type describing what the callback returns. */
    idlType: IDLTypeDescription;
    /** A list of arguments, as in function paramters. */
    arguments: Argument[];
    parent: null;
}

export interface DictionaryType extends AbstractContainer {
    type: "dictionary";
    members: DictionaryMemberType[];
    /** A string giving the name of a dictionary this one inherits from, null otherwise. */
    inheritance: string | null;
    parent: null;
}

export type DictionaryMemberType = FieldType;

export interface FieldType extends AbstractBase {
    type: "field";
    /** The name of the field. */
    name: string;
    /** Boolean indicating whether this is a required field. */
    required: boolean;
    /** An IDL Type describing what field's type. */
    idlType: IDLTypeDescription;
    /** A default value, absent if there is none. */
    default: ValueDescription | null;
    parent: DictionaryType;
}

export interface EnumType extends AbstractBase {
    type: "enum";
    /** The enum's name. */
    name: string;
    /** An array of values (strings). */
    values: Array<{ type: "enum-value"; value: string; parent: EnumType }>;
    /** The container of this type. */
    parent: null;
}

export interface TypedefType extends AbstractBase {
    type: "typedef";
    /** The typedef's name. */
    name: string;
    /** An IDL Type describing what typedef's type. */
    idlType: IDLTypeDescription;
    parent: null;
}

export interface IncludesType extends AbstractBase {
    type: "includes";
    /** The interface that includes an interface mixin. */
    target: string;
    /** The interface mixin that is being included by the target. */
    includes: string;
    parent: null;
}

export interface ConstructorMemberType extends AbstractBase {
    type: "constructor";
    /** An array of arguments for the constructor operation. */
    arguments: Argument[];
    parent: InterfaceType;
}

export interface OperationMemberType extends AbstractBase {
    type: "operation";
    /** Special modifier if exists */
    special: "getter" | "setter" | "deleter" | "static" | "stringifier" | null;
    /** An IDL Type of what the operation returns. If a stringifier, may be absent. */
    idlType: IDLTypeDescription | null;
    /** The name of the operation. If a stringifier, may be null. */
    name: string | null;
    /** An array of arguments for the operation. */
    arguments: Argument[];
    parent: CallbackInterfaceType | InterfaceMixinType | InterfaceType | NamespaceType;
}

export interface AttributeMemberType extends AbstractBase {
    type: "attribute";
    /** The attribute's name. */
    name: string;
    /** Special modifier if exists */
    special: "static" | "stringifier" | null;
    /** True if it's an inherit attribute. */
    inherit: boolean;
    /** True if it's a read-only attribute. */
    readonly: boolean;
    /** An IDL Type for the attribute. */
    idlType: IDLTypeDescription;
    parent: InterfaceMixinType | InterfaceType | NamespaceType;
}

export interface ConstantMemberType extends AbstractBase {
    type: "const";
    /** Whether its type is nullable. */
    nullable: boolean;
    /** An IDL Type of the constant that represents a simple type, the type name. */
    idlType: IDLTypeDescription;
    /** The name of the constant. */
    name: string;
    /** The constant value */
    value: ValueDescription;
    parent: CallbackInterfaceType | InterfaceMixinType | InterfaceType;
}

interface AbstractDeclarationMemberType extends AbstractBase {
    type: DeclarationMemberType["type"];
    /** An array with one or more IDL Types representing the declared type arguments. */
    idlType: IDLTypeDescription[];
    /** Whether the iterable is declared as async. */
    async: boolean;
    /** Whether the maplike or setlike is declared as read only. */
    readonly: boolean;
    /** An array of arguments for the iterable declaration. */
    arguments: Argument[];
    parent: InterfaceMixinType | InterfaceType;
}

export type DeclarationMemberType =
    | IterableDeclarationMemberType
    | MaplikeDeclarationMemberType
    | SetlikeDeclarationMemberType;

export interface IterableDeclarationMemberType extends AbstractDeclarationMemberType {
    type: "iterable";
    idlType: [IDLTypeDescription] | [IDLTypeDescription, IDLTypeDescription];
    async: boolean;
    readonly: false;
}

interface AbstractCollectionLikeMemberType extends AbstractDeclarationMemberType {
    async: false;
    readonly: boolean;
    arguments: [];
}

export interface MaplikeDeclarationMemberType extends AbstractCollectionLikeMemberType {
    type: "maplike";
    idlType: [IDLTypeDescription, IDLTypeDescription];
}

export interface SetlikeDeclarationMemberType extends AbstractCollectionLikeMemberType {
    type: "setlike";
    idlType: [IDLTypeDescription];
}

export interface Argument extends AbstractBase {
    type: "argument";
    /** A default value, absent if there is none. */
    default: ValueDescription | null;
    /** True if the argument is optional. */
    optional: boolean;
    /** True if the argument is variadic. */
    variadic: boolean;
    /** An IDL Type describing the type of the argument. */
    idlType: IDLTypeDescription;
    /** The argument's name. */
    name: string;
    parent: CallbackType | ConstructorMemberType | ExtendedAttribute | OperationMemberType;
}

export interface ExtendedAttribute extends AbstractBase {
    type: "extended-attribute";
    /** The extended attribute's name. */
    name: string;
    /** If the extended attribute takes arguments or if its right-hand side does they are listed here. */
    arguments: Argument[];
    /** If there is a right-hand side, this will capture its type and value. */
    rhs: ExtendedAttributeRightHandSide | null;
    parent: IDLRootType | FieldType | IDLInterfaceMemberType;
}

// prettier-ignore
export type ExtendedAttributeRightHandSide =
    | ExtendedAttributeRightHandSideBase
    | ExtendedAttributeRightHandSideList;

export type ExtendedAttributeRightHandSideBase =
    | ExtendedAttributeRightHandSideIdentifier
    | ExtendedAttributeRightHandSideString
    | ExtendedAttributeRightHandSideDecimal
    | ExtendedAttributeRightHandSideInteger;

export type ExtendedAttributeRightHandSideList =
    | ExtendedAttributeRightHandSideIdentifierList
    | ExtendedAttributeRightHandSideStringList
    | ExtendedAttributeRightHandSideDecimalList
    | ExtendedAttributeRightHandSideIntegerList;

export interface ExtendedAttributeRightHandSideIdentifier {
    type: "identifier";
    value: string;
}

export interface ExtendedAttributeRightHandSideIdentifierList {
    type: "identifier-list";
    value: ExtendedAttributeRightHandSideIdentifier[];
}

export interface ExtendedAttributeRightHandSideString {
    type: "string";
    value: string;
}

export interface ExtendedAttributeRightHandSideStringList {
    type: "string-list";
    value: ExtendedAttributeRightHandSideString[];
}

export interface ExtendedAttributeRightHandSideDecimal {
    type: "decimal";
    value: string;
}

export interface ExtendedAttributeRightHandSideDecimalList {
    type: "decimal-list";
    value: ExtendedAttributeRightHandSideDecimal[];
}

export interface ExtendedAttributeRightHandSideInteger {
    type: "integer";
    value: string;
}

export interface ExtendedAttributeRightHandSideIntegerList {
    type: "integer-list";
    value: ExtendedAttributeRightHandSideInteger[];
}

export interface AbstractValueDescription extends AbstractBase {
    parent: Argument | ConstantMemberType | FieldType;
}

export type ValueDescription =
    | ValueDescriptionString
    | ValueDescriptionNumber
    | ValueDescriptionBoolean
    | ValueDescriptionNull
    | ValueDescriptionInfinity
    | ValueDescriptionNaN
    | ValueDescriptionSequence
    | ValueDescriptionDictionary;

export interface ValueDescriptionString extends AbstractValueDescription {
    type: "string";
    value: string;
}

export interface ValueDescriptionNumber extends AbstractValueDescription {
    type: "number";
    value: string;
}

export interface ValueDescriptionBoolean extends AbstractValueDescription {
    type: "boolean";
    value: boolean;
}

export interface ValueDescriptionNull extends AbstractValueDescription {
    type: "null";
}

export interface ValueDescriptionInfinity extends AbstractValueDescription {
    type: "Infinity";
    negative: boolean;
}

export interface ValueDescriptionNaN extends AbstractValueDescription {
    type: "NaN";
}

export interface ValueDescriptionSequence extends AbstractValueDescription {
    type: "sequence";
    value: [];
}

export interface ValueDescriptionDictionary extends AbstractValueDescription {
    type: "dictionary";
}