Comprehensive Mirrors API for ECMAScript

mirrors.ts

declare namespace Reflect {
    /**
     * Gets a mirror for the target.
     *
     * @param target The target of the mirror.
     * @param usage The intended usage for the mirror, either a read-only introspection mirror or a writable mutation mirror. Default "mutation".
     * @returns A mirror for the provided target.
     */
    function mirror(target: any, usage?: "introspection" | "mutation"): ObjectMirror | FunctionMirror | ClassMirror | undefined | null;
}

/** A read-only collection. */
interface ReadonlyCollection<T> extends ReadonlyArray<T>, Iterable<T> {
}

//
// Mirrors
//
// These interfaces describe the shape of each mirror.
// NOTE: Inherited members are duplicated on subtypes for easier reference.

/** The available kinds of mirrors */
type MirrorKind = "object" | "function" | "class" | "constructor" | "method" | "accessor" | "property" | "get" | "set" | "field" | "property" | "parameter";

/** The available states of mirrors */
type MirrorState = "declaration" | "introspection" | "mutation";

/** A Mirror for a declaration. */
interface Mirror {
    /**
     * Gets the kind of mirror this represents.
     *
     * The kind indicates which  specific mirror interface describes the shape of this mirror:
     *  "object"        - ObjectMirror
     *  "function"      - FunctionMirror
     *  "class"         - ClassMirror
     *  "constructor"   - ConstructorMirror
     *  "method"        - MethodMirror
     *  "accessor"      - AccessorMirror
     *  "get"           - GetterMirror
     *  "set"           - SetterMirror
     *  "property"      - PropertyMirror
     *  "field"         - FieldMirror
     *  "parameter"     - ParameterMirror
     */
    readonly kind: MirrorKind;

    /**
     * Gets the state of the mirror.
     *
     * When a mirror is in the "declaration" state, the underlying target for the mirror does not
     * yet have a runtime value. Any method or property that directly interacts with the runtime
     * value will likely throw an error.
     *
     * When a mirror is in the "introspection" state, any method or property that would directly
     * mutate the runtime value will likely throw an error.
     *
     * When a mirror is in the "mutation" state, any method that would directly mutate the
     * declaration will likely throw an error.
     */
    readonly state: MirrorState;

    /**
     * Gets an introspection (read-only) mirror for this mirror.
     */
    forIntrospection(): Mirror;
}

/** A Mirror that supports metadata. */
interface MetadataMirror extends Mirror, MetadataProvider {
}

/** A Mirror for an object literal or value. */
interface ObjectMirror extends Mirror {
    /** Gets the kind of mirror this represents. For an ObjectMirror this is always "object". (Inherited from Mirror) */
    readonly kind: "object";

    /** Gets the state of the mirror. (Inherited from Mirror) */
    readonly state: MirrorState;

    /** Gets a mirror for the class from which this object was instantiated, if available. */
    readonly classMirror: ClassMirror | undefined;

    /** Gets a value indicating whether the class is extensible. */
    readonly extensible: boolean;

    /**
     * Gets the value for this mirror.
     *
     * @throws Accessing this property will throw an error if the mirror's state is "declaration".
     */
    readonly value: any;

    /**
     * Tests for the existance of a named member of an object.
     *
     * @param name The name of the member.
     * @param filter Options used to filter members.
     * @returns true if the member is defined; otherwise, false.
     */
    hasMember(name: string | symbol | PrivateSlot, filter?: ObjectMemberFilter): boolean;

    /**
     * Gets a named member of an object.
     *
     * @param name The name of the member.
     * @param filter Options used to filter members.
     * @returns A MemberMirror for the named member if it exists; otherwise, undefined.
     */
    getMember(name: string | symbol | PrivateSlot, filter?: ObjectMemberFilter): MemberLikeMirror | undefined;

    /**
     * Gets the members of an object.
     *
     * Members whose names are PrivateSlot objects will only be returned if the mirror's state is "declaration".
     *
     * @param filter Options used to filter members.
     * @returns An Iterable of members that match the provided filter.
     */
    getMembers(filter?: ObjectMemberFilter): Iterable<MemberLikeMirror>;

    /**
     * Deletes a named member member of an object.
     *
     * @param name The name of the member.
     * @param filter Options used to filter members.
     * @returns true if the member was successfully deleted; otherwise, false.
     */
    deleteMember(name: string | symbol | PrivateSlot, filter?: ObjectMemberDeleteFilter): boolean;

    /**
     * Defines a method on an object.
     *
     * @param name The name of the method.
     * @param descriptor The descriptor for the method.
     * @returns A MethodMirror for the method.
     * @throws This method will throw an error if the mirror's state is "introspection".
     */
    defineMethod(name: string | symbol | PrivateSlot, descriptor: MethodDescriptor): MethodMirror;

    /**
     * Defines an accessor on an object.
     *
     * @param name The name of the accessor.
     * @param descriptor The descriptor for the accessor.
     * @returns An AccessorMirror for the accessor.
     * @throws This method will throw an error if the mirror's state is "introspection".
     */
    defineAccessor(name: string | symbol | PrivateSlot, descriptor: AccessorDescriptor): AccessorMirror;

    /**
     * Defines a data property on an object.
     *
     * @param name The name of the property.
     * @param descriptor The descriptor for the property.
     * @returns A PropertyMirror for the property.
     * @throws This method will throw an error if the mirror's state is "introspection".
     */
    defineProperty(name: string | symbol | PrivateSlot, descriptor: DataDescriptor): PropertyMirror;

    /**
     * Defines an opaque private slot.
     *
     * @param name The name of the private slot.
     * @returns A PrivateSlot.
     * @throws This method will throw an error if the mirror's state not "declaration".
     */
    definePrivateSlot(name?: string): PrivateSlot;

    /**
     * Gets the prototype for the object.
     *
     * @throws This method will throw an error if the mirror's state is "introspection".
     */
    getPrototype(): any;

    /**
     * Sets the prototype for the object.
     */
    setPrototype(proto: any): boolean;

    /**
     * Gets the value of the named property.
     *
     * @param name The name of the property.
     * @throws This method will throw an error if the mirror's state is "declaration".
     */
    get(name: string | symbol): any;

    /**
     * Sets the value of the named property.
     *
     * @param name The name of the property.
     * @param value The value for the property.
     * @returns true if the property was set successfully; otherwise, false.
     */
    set(name: string | symbol, value: any): boolean;

    /**
     * Prevents extensions to the class.
     *
     * @returns true if extensions could be prevented; otherwise, false.
     */
    preventExtensions(): boolean;

    /**
     * Gets an introspection (read-only) mirror for this mirror. (Inherited from Mirror)
     */
    forIntrospection(): ObjectMirror;
}

/** Options used to filter object members. */
interface ObjectMemberFilter {
    /**
     * Indicates whether to only include own members.
     *
     * If true, only own members will be included.
     * If false or undefined, own members will be unioned with members defined on the prototype chain.
     */
    own?: boolean,

    /**
     * Indicates the kind of members to include.
     *
     * If "method", only methods will be included.
     * If "accessor", only accessors will be included.
     * If "property", only data properties will be included.
     * If undefined, all members will be included.
     */
    kind?: "method" | "accessor" | "property";
}

/** Options used to filter object members. */
interface ObjectMemberDeleteFilter {
    /**
     * Indicates the kind of members to include.
     *
     * If "method", only methods will be included.
     * If "accessor", only accessors will be included.
     * If "property", only data properties will be included.
     * If undefined, all members will be included.
     */
    kind?: "method" | "accessor" | "property";
}

/** A Mirror for a function declaration or function expression. */
interface FunctionMirror extends MetadataMirror {
    /** Gets the kind of mirror this represents. For a FunctionMirror this is always "function". (Inherited from Mirror) */
    readonly kind: "function";

    /** Gets the state of the mirror. (Inherited from Mirror) */
    readonly state: MirrorState;

    /** Gets the name of the function, if defined. */
    readonly name: string | undefined;

    /** Gets the declared parameters for the function. */
    readonly parameters: ReadonlyCollection<ParameterMirror>;

    /**
     * Gets or sets the underlying function for the function mirror.
     *
     * @throws Setting this property will throw an error if the mirror state is not "declaration".
     */
    value: Function;

    /**
     * Invokes the underlying function with the supplied "this" argument and argument list.
     *
     * @param thisArgument The value to use as the "this" argument for the function invocation.
     * @param argumentsList The arguments to use for the function invocation.
     * @returns The result of invoking the function.
     * @throws This method will throw an error if the mirror's current state is "declaration".
     */
    apply(thisArgument: any, argumentsList: ArrayLike<any> | Iterable<any>): any;

    /**
     * Constructs a new object using the underlying function as a constructor.
     *
     * @param argumentsList The arguments to use for the function invocation.
     * @param newTarget An optional target to use as the "new.target" binding for the function invocation.
     * @returns The result of invoking the underlying function as a constructor.
     * @throws This method will throw an error if the mirror's current state is "declaration".
     */
    construct(argumentsList: ArrayLike<any>, newTarget?: any): any;

    /**
     * Gets an introspection (read-only) mirror for this mirror. (Inherited from Mirror)
     */
    forIntrospection(): FunctionMirror;
}

/** A Mirror for a class declaration or class expression. */
interface ClassMirror extends MetadataMirror {
    /** Gets the kind of mirror this represents. For a ClassMirror this is always "class". (Inherited from Mirror) */
    readonly kind: "class";

    /** Gets the state of the mirror. (Inherited from Mirror) */
    readonly state: MirrorState;

    /** The name of the class, if defined. */
    readonly name: string | undefined;

    /** Gets the constructor for the class. */
    readonly classConstructor: ConstructorMirror;

    /** Gets the mirror for the superclass. */
    readonly superClass: ClassMirror | undefined | null;

    /** Gets a value indicating whether the class is extensible. */
    readonly extensible: boolean;

    /**
     * Tests for the existance of a named member of a class.
     *
     * @param name The name of the member.
     * @param filter Options used to filter members.
     * @returns true if the member is defined; otherwise, false.
     */
    hasMember(name: string | symbol | PrivateSlot, filter?: ClassMemberFilter): boolean;

    /**
     * Gets a named member of a class.
     *
     * @param name The name of the member.
     * @param filter Options used to filter members.
     * @returns A MemberMirror for the named member if it exists; otherwise, undefined.
     */
    getMember(name: string | symbol | PrivateSlot, filter?: ClassMemberFilter): MemberLikeMirror | undefined;

    /**
     * Gets the members of a class.
     *
     * Members whose names are PrivateSlot objects will only be returned if the mirror's state is "declaration".
     *
     * @param filter Options used to filter members.
     * @returns An Iterable of members that match the provided filter.
     */
    getMembers(filter?: ClassMemberFilter): Iterable<MemberLikeMirror>;

    /**
     * Deletes a named member member of a class.
     *
     * @param name The name of the member.
     * @param filter Options used to filter members.
     * @returns true if the member was successfully deleted; otherwise, false.
     */
    deleteMember(name: string | symbol | PrivateSlot, filter?: ClassMemberDeleteFilter): boolean;

    /**
     * Defines a method on a class.
     *
     * @param name The name of the method.
     * @param descriptor The descriptor for the method.
     * @returns A MethodMirror for the method.
     * @throws This method will throw an error if the mirror's current state is "introspection".
     */
    defineMethod(name: string | symbol | PrivateSlot, descriptor: MethodDescriptor): MethodMirror;

    /**
     * Defines an accessor on a class.
     *
     * @param name The name of the accessor.
     * @param descriptor The descriptor for the accessor.
     * @returns An AccessorMirror for the accessor.
     * @throws This method will throw an error if the mirror's current state is "introspection".
     */
    defineAccessor(name: string | symbol | PrivateSlot, descriptor: AccessorDescriptor): AccessorMirror;

    /**
     * Defines a data property on a class.
     *
     * @param name The name of the property.
     * @param descriptor The descriptor for the property.
     * @returns A DataPropertyMirror for the property.
     * @throws This method will throw an error if the mirror's current state is "introspection".
     */
    defineProperty(name: string | symbol | PrivateSlot, descriptor: DataDescriptor): PropertyMirror;

    /**
     * Defines a field on a class.
     *
     * @param name The name of the field.
     * @param descriptor The descriptor for the field.
     * @returns A FieldMirror for the field.
     * @throws This method will throw an error if the mirror's current state is not "declaration".
     */
    defineField(name: string | symbol | PrivateSlot, descriptor: FieldDescriptor): FieldMirror;

    /**
     * Defines an opaque private slot.
     *
     * @param name The name of the private slot.
     * @returns A PrivateSlot.
     * @throws This method will throw an error if the mirror's state not "declaration".
     */
    definePrivateSlot(name?: string): PrivateSlot;

    /**
     * Prevents extensions to the class.
     *
     * @returns true if extensions could be prevented; otherwise, false.
     */
    preventExtensions(): boolean;

    /**
     * Creates an instance of the provided class.
     *
     * @param argumentsList The arguments to use for the function invocation.
     * @param newTarget An optional target to use as the "new.target" binding for the function invocation.
     * @returns The result of instantiating a new instance of the underlying class.
     * @throws This method will throw an error if the mirror's current state is "declaration".
     */
    construct(argumentsList: ArrayLike<any> | Iterable<any>, newTarget?: any): any;

    /**
     * Gets an introspection (read-only) mirror for this mirror. (Inherited from Mirror)
     */
    forIntrospection(): ClassMirror;
}

/** Options used to filter class members. */
interface ClassMemberFilter {
    /**
     * Indicates whether to include static or non-static members.
     *
     * If true, only static members will be included.
     * If false, only non-static (prototype and instance) members will be included.
     * If undefined, all members will be included.
     */
    static?: boolean;

    /**
     * Indicates whether to only include own members.
     *
     * If true, only own members will be included.
     * If false or undefined, own members will be unioned with members defined on each supertype.
     */
    own?: boolean,

    /**
     * Indicates the kind of members to include.
     *
     * If "method", only methods will be included.
     * If "accessor", only accessors will be included.
     * If "property", only data properties will be included.
     * If "field", only fields will be included.
     * If undefined, all members will be included.
     */
    kind?: "method" | "accessor" | "property" | "field";
}

/** Options used to filter class members. */
interface ClassMemberDeleteFilter {
    /**
     * Indicates whether to include static or non-static members.
     *
     * If true, only static members will be included.
     * If false, only non-static (prototype and instance) members will be included.
     * If undefined, all members will be included.
     */
    static?: boolean;

    /**
     * Indicates the kind of members to include.
     *
     * If "method", only methods will be included.
     * If "accessor", only accessors will be included.
     * If "property", only data properties will be included.
     * If "field", only fields will be included.
     * If undefined, all members will be included.
     */
    kind?: "method" | "accessor" | "property" | "field";
}

/** Flags used to target a specific class member. */
interface ClassMemberFlags {
    /**
     * Indicates whether to target a static or non-static member.
     *
     * If true, indicates a static member.
     * If false or undefined, indicates a non-static (prototype or instance) member.
     */
    static?: boolean;
}

/** A Mirror for the constructor of a class. */
interface ConstructorMirror extends MetadataMirror {
    /** Gets the kind of mirror this represents. For a ConstructorMirror this is always "constructor". (Inherited from Mirror) */
    readonly kind: "constructor";

    /** Gets the state of the mirror. (Inherited from Mirror) */
    readonly state: MirrorState;

    /** Gets the name of the class, if defined. */
    readonly name: string | undefined;

    /** Gets the parent ClassMirror for this member. */
    readonly parent: ClassMirror;

    /** Gets the parameters for the constructor. */
    readonly parameters: ReadonlyCollection<ParameterMirror>;

    /**
     * Gets or sets the underlying function for the constructor.
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    value: Function;

    /**
     * Creates an instance of the provided class.
     *
     * @param argumentsList The arguments to use for the function invocation.
     * @param newTarget An optional target to use as the "new.target" binding for the function invocation.
     * @returns The result of instantiating a new instance of the underlying class.
     * @throws This method will throw an error if the mirror's current state is "declaration".
     */
    construct(argumentsList: ArrayLike<any> | Iterable<any>, newTarget?: any): any;

    /**
     * Gets an introspection (read-only) mirror for this mirror. (Inherited from Mirror)
     */
    forIntrospection(): ConstructorMirror;
}

/** The kinds legal for a member of a class or object. */
type MemberMirrorKind = "method" | "accessor" | "property" | "field";

/** A Mirror for a member defined on a class or object. */
interface MemberMirror extends MetadataMirror {
    /** Gets the kind of mirror this represents. (Inherited from Mirror) */
    readonly kind: MemberMirrorKind;

    /** Gets the state of the mirror. (Inherited from Mirror) */
    readonly state: MirrorState;

    /** Gets the name of the member. */
    readonly name: string | symbol | PrivateSlot;

    /** Gets the parent ClassMirror or ObjectMirror for this member. */
    readonly parent: ClassMirror | ObjectMirror;

    /** Gets a value indicating whether the member is a static member of the class. */
    readonly static: boolean;

    /**
     * Gets or sets a value indicating whether the method is enumerable.
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    enumerable: boolean;

    /**
     * Gets or sets a value indicating whether the method is configurable.
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    configurable: boolean;

    /**
     * Gets the member this method shadows on its superclass, if one exists.
     */
    getShadowedMember(): MemberMirror | undefined;

    /**
     * Gets an introspection (read-only) mirror for this mirror. (Inherited from Mirror)
     */
    forIntrospection(): MemberMirror;
}

/** A Mirror for a method defined on a class or object. */
interface MethodMirror extends MemberMirror {
    /** Gets the kind of mirror this represents. For a MethodMirror this is always "method". (Inherited from Mirror) */
    readonly kind: "method";

    /** Gets the state of the mirror. (Inherited from Mirror) */
    readonly state: MirrorState;

    /** Gets the name of the method. (Inherited from MemberMirror) */
    readonly name: string | symbol | PrivateSlot;

    /** Gets the parent ClassMirror or ObjectMirror for this method. (Inherited from MemberMirror) */
    readonly parent: ClassMirror | ObjectMirror;

    /** Gets a value indicating whether the method is a static member of the class. (Inherited from MemberMirror) */
    readonly static: boolean;

    /** Gets a read-only array for the declared parameters of the method. */
    readonly parameters: ReadonlyCollection<ParameterMirror>;

    /**
     * Gets or sets a value indicating whether the method is enumerable. (Inherited from PropertyLikeMirror)
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    enumerable: boolean;

    /**
     * Gets or sets a value indicating whether the method is configurable. (Inherited from PropertyLikeMirror)
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    configurable: boolean;

    /**
     * Gets or sets a value indicating whether the method is writable.
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    writable: boolean;

    /**
     * Gets or sets the underlying function for the method.
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    value: Function;

    /**
     * Gets the member this method shadows on its superclass, if one exists. (Inherited from PropertyLikeMirror)
     */
    getShadowedMember(): MemberMirror | undefined;

    /**
     * Invokes the underlying function with the supplied "this" argument and argument list.
     *
     * @param thisArgument The value to use as the "this" argument for the function invocation.
     * @param argumentsList The arguments to use for the function invocation.
     * @returns The result of invoking the function.
     * @throws This method will throw an error if the mirror's current state is "declaration".
     */
    apply(thisArgument: any, argumentsList: ArrayLike<any> | Iterable<any>): any;

    /**
     * Gets an introspection (read-only) mirror for this mirror. (Inherited from Mirror)
     */
    forIntrospection(): MethodMirror;
}

/** A Mirror for an accessor defined on a class. */
interface AccessorMirror extends MemberMirror {
    /** Gets the kind of mirror this represents. For an AccessorMirror this is always "accessor". (Inherited from Mirror) */
    readonly kind: "accessor";

    /** Gets the state of the mirror. (Inherited from Mirror) */
    readonly state: MirrorState;

    /** Gets the name of the method. (Inherited from MemberMirror) */
    readonly name: string | symbol | PrivateSlot;

    /** Gets the parent ClassMirror or ObjectMirror for this method. (Inherited from MemberMirror) */
    readonly parent: ClassMirror | ObjectMirror;

    /** Gets a value indicating whether the method is a static member of the class. (Inherited from MemberMirror) */
    readonly static: boolean;

    /** Gets a value indicating whether the accessor has a get method. */
    readonly readable: boolean;

    /** Gets a value indicating whether the accessor has a set method. */
    readonly writable: boolean;

    /** Gets the mirror for the accessor's getter, if defined. */
    readonly get: GetterMirror | undefined;

    /** Gets the mirror for the accessor's setter, if defined. */
    readonly set: SetterMirror | undefined;

    /**
     * Gets or sets a value indicating whether the accessor is enumerable. (Inherited from PropertyLikeMirror)
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    enumerable: boolean;

    /**
     * Gets or sets a value indicating whether the accessor is configurable. (Inherited from PropertyLikeMirror)
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    configurable: boolean;

    /**
     * Gets the member this accessor shadows on its superclass, if one exists. (Inherited from PropertyLikeMirror)
     */
    getShadowedMember(): MemberMirror | undefined;

    /**
     * Invokes the getter using the supplied target.
     *
     * @param target The value to use as the this argument for the function invocation.
     * @returns The result of invoking the getter.
     * @throws This method will throw an error if the mirror's current state is "declaration".
     * @throws This method will throw an error if the mirror does not have a get method.
     */
    getValue(target: any): any;

    /**
     * Invokes the setter using the supplied target and value.
     *
     * @param target The value to use as the this argument for the function invocation.
     * @param value The value to pass to the setter.
     * @returns true if the value could be set; otherwise, false.
     * @throws This method will throw an error if the mirror's current state is "declaration".
     */
    setValue(target: any, value: any): boolean;

    /**
     * Gets an introspection (read-only) mirror for this mirror. (Inherited from Mirror)
     */
    forIntrospection(): AccessorMirror;
}

/** A Mirror for a getter defined on a class. */
interface GetterMirror extends MetadataMirror {
    /** Gets the kind of mirror this represents. For a GetterMirror this is always "get". (Inherited from Mirror) */
    readonly kind: "get";

    /** Gets the state of the mirror. (Inherited from Mirror) */
    readonly state: MirrorState;

    /** Gets the name of the accessor. */
    readonly name: string | symbol | PrivateSlot;

    /** Gets the parent AccessorMirror for this get method. */
    readonly parent: AccessorMirror;

    /** Gets a value indicating whether the get method is a static member of the class. */
    readonly static: boolean;

    /** Gets a read-only array for the declared parameters of the get method. */
    readonly parameters: ReadonlyCollection<ParameterMirror>;

    /**
     * Gets or sets the underlying function for the get method.
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    value: Function;

    /**
     * Invokes the underlying function with the supplied "this" argument and argument list.
     *
     * @param thisArgument The value to use as the "this" argument for the function invocation.
     * @param argumentsList The arguments to use for the function invocation.
     * @returns The result of invoking the function.
     * @throws This method will throw an error if the mirror's current state is "declaration".
     */
    apply(thisArgument: any, argumentsList: ArrayLike<any> | Iterable<any>): any;

    /**
     * Gets an introspection (read-only) mirror for this mirror. (Inherited from Mirror)
     */
    forIntrospection(): GetterMirror;
}

/** A Mirror for a setter defined on a class. */
interface SetterMirror extends MetadataMirror {
    /** Gets the kind of mirror this represents. For a SetterMirror this is always "set". (Inherited from Mirror) */
    readonly kind: "set";

    /** Gets the state of the mirror. (Inherited from Mirror) */
    readonly state: MirrorState;

    /** Gets the name of the accessor. */
    readonly name: string | symbol | PrivateSlot;

    /** Gets the parent AccessorMirror for this set method. */
    readonly parent: AccessorMirror;

    /** Gets a value indicating whether the set method is a static member of the class. */
    readonly static: boolean;

    /** Gets a read-only array for the declared parameters of the set method. */
    readonly parameters: ReadonlyCollection<ParameterMirror>;

    /**
     * Gets or sets the underlying function for the set method.
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    value: Function;

    /**
     * Invokes the underlying function with the supplied "this" argument and argument list.
     *
     * @param thisArgument The value to use as the "this" argument for the function invocation.
     * @param argumentsList The arguments to use for the function invocation.
     * @returns The result of invoking the function.
     * @throws This method will throw an error if the mirror's current state is "declaration".
     */
    apply(thisArgument: any, argumentsList: ArrayLike<any> | Iterable<any>): any;

    /**
     * Gets an introspection (read-only) mirror for this mirror. (Inherited from Mirror)
     */
    forIntrospection(): SetterMirror;
}

/** A Mirror for a property defined on a class or object. */
interface PropertyMirror extends MemberMirror {
    /** Gets the kind of mirror this represents. For a DataPropertyMirror this is always "property". (Inherited from Mirror) */
    readonly kind: "property";

    /** Gets the state of the mirror. (Inherited from Mirror) */
    readonly state: MirrorState;

    /** Gets the name of the property. (Inherited from MemberMirror) */
    readonly name: string | symbol | PrivateSlot;

    /** Gets the parent ClassMirror or ObjectMirror for this property. (Inherited from MemberMirror) */
    readonly parent: ClassMirror | ObjectMirror;

    /** Gets a value indicating whether the property is a static member of the class. (Inherited from MemberMirror) */
    readonly static: boolean;

    /**
     * Gets or sets a value indicating whether the property is enumerable. (Inherited from PropertyLikeMirror)
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    enumerable: boolean;

    /**
     * Gets or sets a value indicating whether the property is configurable. (Inherited from PropertyLikeMirror)
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    configurable: boolean;

    /**
     * Gets or sets a value indicating whether the property is writable.
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    writable: boolean;

    /**
     * Gets or sets the underlying value for the property.
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    value: any;

    /**
     * Gets the member this property shadows on its superclass, if one exists. (Inherited from PropertyLikeMirror)
     */
    getShadowedMember(): MemberMirror | undefined;

    /**
     * Gets an introspection (read-only) mirror for this mirror. (Inherited from Mirror)
     */
    forIntrospection(): PropertyMirror;
}

/** A Mirror for a field on a class. */
interface FieldMirror extends MemberMirror {
    /** Gets the kind of mirror this represents. For a FieldMirror this is always "field". (Inherited from Mirror) */
    readonly kind: "field";

    /** Gets the state of the mirror. (Inherited from Mirror) */
    readonly state: MirrorState;

    /** Gets the name of the field. (Inherited from MemberMirror) */
    readonly name: string | symbol | PrivateSlot;

    /** Gets the parent class for this field. (Inherited from MemberMirror) */
    readonly parent: ClassMirror;

    /** Gets a value indicating whether the field is a static member of the class. (Inherited from MemberMirror) */
    readonly static: boolean;

    /**
     * Gets or sets a value indicating whether the field is enumerable after initialization. (Inherited from PropertyLikeMirror)
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    enumerable: boolean;

    /**
     * Gets or sets a value indicating whether the field is configurable after initialization. (Inherited from PropertyLikeMirror)
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    configurable: boolean;

    /**
     * Gets or sets a value indicating whether the field is writable after initialization.
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    writable: boolean;

    /**
     * Gets or sets an initializer to evaluate when the field is initialized.
     *
     * @throws Setting this property will throw an error if the mirror's current state is not "declaration".
     */
    initializer: Function | undefined;

    /**
     * Gets the member this field shadows on its superclass, if one exists. (Inherited from PropertyLikeMirror)
     */
    getShadowedMember(): MemberMirror | undefined;

    /**
     * Gets an introspection (read-only) mirror for this mirror. (Inherited from Mirror)
     */
    forIntrospection(): FieldMirror;
}

/** The known subtypes of MemberMirror */
type MemberLikeMirror = MethodMirror | AccessorMirror | PropertyMirror | FieldMirror | MemberMirror;

/** A Mirror for a parameter. */
interface ParameterMirror extends MetadataMirror {
    /** Gets the kind of mirror this represents. For a ParameterMirror this is always "parameter". (Inherited from Mirror) */
    readonly kind: "parameter";

    /** Gets the state of the mirror. (Inherited from Mirror) */
    readonly state: MirrorState;

    /** Gets the name of the parameter, if defined. */
    readonly name: string | undefined;

    /** Gets the parent mirror for this parameter. */
    readonly parent: ConstructorMirror | MethodMirror | GetterMirror | SetterMirror | FunctionMirror;

    /** Gets the index of this parameter. */
    readonly index: number;

    /**
     * Gets an introspection (read-only) mirror for this mirror. (Inherited from Mirror)
     */
    forIntrospection(): ParameterMirror;
}

/** The known function-like mirrors. */
type FunctionLikeMirror = ConstructorMirror | MethodMirror | GetterMirror | SetterMirror | FunctionMirror;

/** A private slot defined on an object or class. */
interface PrivateSlot {
    /**
     * Gets a value indicating whether the private slot is defined on the object.
     *
     * @param object An object.
     * @returns True if the slot is defined on the object; otherwise, false.
     * @throws This method will throw an error if object is not an Object or is null.
     */
    isDefined(object: Object): boolean;

    /**
     * Gets the value of the private slot on an object.
     *
     * @param object An object.
     * @returns The current value of the private slot.
     * @throws This method will throw an error if object is not an Object, is null, or does not have the private slot defined.
     */
    getValue(object: Object): any;

    /**
     * Sets the value of a private slot on an object.
     *
     * @param object An object.
     * @param value The value.
     * @returns True if the object has the private slot defined and the value was set successfully; otherwise, false.
     * @throws This method will throw an error if object is not an Object or is null.
     */
    setValue(object: Object, value: any): boolean;

    /**
     * Gets a debug-friendly string for the PrivateSlot.
     */
    toString(): string;
}

//
// Decorators
//
// These types indicate the expected call signature for a decorator function.

/** General-purpose decorator. */
type DecoratorFunction = (mirror: Mirror) => void;

/** Decorator for a class declaration or expression. */
type ClassDecoratorFunction = (mirror: ClassMirror) => void;

/** Decorator for a constructor declaration. */
type ConstructorDecoratorFunction = (mirror: ConstructorMirror) => void;

/** Decorator for a method declaration. */
type MethodDecoratorFunction = (mirror: MethodMirror) => void;

/** Decorator for a get accessor declaration. */
type GetterDecoratorFunction = (mirror: GetterMirror) => void;

/** Decorator for a set accessor declaration. */
type SetterDecoratorFunction = (mirror: SetterMirror) => void;

/** Decorator for a property assignment. */
type PropertyDecoratorFunction = (mirror: PropertyMirror) => void;

/** Decorator for a field declaration. */
type FieldDecoratorFunction = (mirror: FieldMirror) => void;

/** Decorator for a parameter declaration. */
type ParameterDecoratorFunction = (mirror: ParameterDecorator) => void;

/** Decorator for a function declaration, function expression, or arrow function. */
type FunctionDecoratorFunction = (mirror: FunctionMirror) => void;

//
// Descriptors
//
// These types describe the valid options for defining members.
// NOTE: Inherited members are duplicated on subtypes for easier reference.

/** A descriptor used to define a member on a class or object. */
interface MemberDescriptor {
    /** A value indicating whether the member is a static member of the class. Default false. */
    static?: boolean;
}

/** A descriptor used to define a property-like member on a class or object. */
interface PropertyLikeDescriptor extends MemberDescriptor {
    /** A value indicating whether the member is a static member of the class. Default false. (Inherited from MemberDescriptor) */
    static?: boolean;

    /** A value indicating whether the member is enumerable. Default false. */
    enumerable?: boolean;

    /** A value indicating whether the member is configurable. Default false. */
    configurable?: boolean;
}

/** A descriptor used to define a method on a class or object. */
interface MethodDescriptor extends PropertyLikeDescriptor {
    /** A value indicating whether the method is a static member of the class. Default false. (Inherited from MemberDescriptor) */
    static?: boolean;

    /** A value indicating whether the method is enumerable. Default false. (Inherited from PropertyLikeDescriptor) */
    enumerable?: boolean;

    /** A value indicating whether the method is configurable. Default false. (Inherited from PropertyLikeDescriptor) */
    configurable?: boolean;

    /** A value indicating whether the method is writable. Default false. */
    writable?: boolean;

    /** The underlying function for the method. */
    value: Function;
}

/** A descriptor used to define a get or set accessor on a class or object. */
interface AccessorDescriptor extends PropertyLikeDescriptor {
    /**
     * A value indicating whether the accessor is a static member of the class. Default false. (Inherited from MemberDescriptor) */
    static?: boolean;

    /** A value indicating whether the accessor is enumerable. Default false. (Inherited from PropertyLikeDescriptor) */
    enumerable?: boolean;

    /** A value indicating whether the accessor is configurable. Default false. (Inherited from PropertyLikeDescriptor) */
    configurable?: boolean;

    /** The underlying function for the getter. */
    get?(): any;

    /** The underlying function for the setter. */
    set?(value: any): void;
}

/** A descriptor used to define a data property on a class or object. */
interface DataDescriptor extends PropertyLikeDescriptor {
    /** A value indicating whether the property is a static member of the class. Default false. (Inherited from MemberDescriptor) */
    static?: boolean;

    /** A value indicating whether the data property is enumerable. Default false. (Inherited from PropertyLikeDescriptor) */
    enumerable?: boolean;

    /** A value indicating whether the data property is configurable. Default false. (Inherited from PropertyLikeDescriptor) */
    configurable?: boolean;

    /** A value indicating whether the data property is writable. Default false. */
    writable?: boolean;

    /** The underlying value for the data property. */
    value: any;
}

/** A descriptor used to define a field on a class. */
interface FieldDescriptor extends PropertyLikeDescriptor {
    /** A value indicating whether the property is a static member of the class. Default false. (Inherited from MemberDescriptor) */
    static?: boolean;

    /** A value indicating whether the field is enumerable after initialization. Default false. (Inherited from PropertyLikeDescriptor) */
    enumerable?: boolean;

    /** A value indicating whether the field is configurable after initialization. Default false. (Inherited from PropertyLikeDescriptor) */
    configurable?: boolean;

    /** A value indicating whether the field is writable after initialization. Default false. */
    writable?: boolean;

    /** An optional function used to set the initial value of the field. */
    initializer?: Function;
}

//
// Metadata
//
// The following types are used to support metadata-producing decorators and are intended for
// a future proposal.

/** Provides metadata for mirrors. */
interface MetadataProvider {
    /**
     * Gets a value indicating whether the provided metadata key exists.
     *
     * @param key The metadata key.
     * @param filter Options used to filter results.
     * @returns true if the mirror has the provided metadata key; otherwise, false.
     */
    hasMetadata(key: any, filter?: MetadataFilter): boolean;

    /**
     * Gets the metadata value for the provided metadata key.
     *
     * @param key The metadata key.
     * @param filter Options used to filter results.
     * @returns The metadata value if the provided key exists; otherwise, undefined.
     */
    getMetadata(key: any, filter?: MetadataFilter): any;

    /**
     * Gets the metadata keys for the declaration.
     *
     * @param filter Options used to filter results.
     * @returns An iterable of all defined metadata keys.
     */
    getMetadataKeys(filter?: MetadataFilter): Iterable<any>;

    /**
     * Gets the metadata keys and values for the declaration.
     *
     * @param filter Options used to filter results.
     * @returns An iterable of all defined metadata keys and values.
     */
    getMetadataEntries(filter?: MetadataFilter): Iterable<[any, any]>;

    /**
     * Defines a metadata key/value pair.
     *
     * @param key The metadata key.
     * @param value The metadata value.
     * @returns true if the metadata could be defined; otherwise, false.
     */
    defineMetadata(key: any, value: any): boolean;

    /**
     * Deletes metadata with the provided key.
     *
     * @param key The metadata key.
     * @returns true if the metadata could be deleted; otherwise false.
     */
    deleteMetadata(key: any): boolean;
}

/** Additional options provided to various methods on MetadataProvider. */
interface MetadataFilter {
    /**
     * Indicates whether to only include own metadata. Default false.
     *
     * If true, only metadata defined on this mirror is used.
     * If false, metadata from this mirror is unioned with metadata from any shadowed declaration
     * from each superclass.
     */
    own?: boolean;
}

//
// Examples
//
// The following are examples of application and definition of various decorators

// @ClassDecorator
// class C {
//     @FieldDecorator
//     y = 1;
//
//     @ConstructorDecorator
//     constructor() {}
//
//     @MethodDecorator
//     static method(@ParameterDecorator x) { }
//
//     @GetterDecorator
//     get x() { }
//
//     @SetterDecorator
//     set x(value) { }
// }

// @FunctionDecorator
// const function f() { }

// const obj = {
//     @MethodDecorator
//     method(@ParameterDecorator x) { },
//
//     @PropertyDecorator
//     y: 1,
//
//     @GetterDecorator
//     get x() { },
//
//     @SetterDecorator
//     set x(value) { }
// }

// function ClassDecorator(mirror: ClassMirror) { /* ... */ }
// function FieldDecorator(mirror: FieldMirror) { /* ... */ }
// function ConstructorDecorator(mirror: ConstructorMirror) { /* ... */ }
// function MethodDecorator(mirror: MethodMirror) { /* ... */ }
// function ParameterDecorator(mirror: ParameterMirror) { /* ... */ }
// function GetterDecorator(mirror: GetterMirror) { /* ... */ }
// function SetterDecorator(mirror: SetterMirror) { /* ... */ }
// function FunctionDecorator(mirror: FunctionMirror) { /* ... */ }
// function PropertyDecorator(mirror: PropertyMirror) { /* ... */ }

The most recent version can now be found at https://github.com/rbuckton/ecmascript-mirrors.