@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.345.1-beta.20250704.94554

package/src/foundry/common/prosemirror/string-serializer.d.mts

@@ -1,20 +1,6 @@
+import type { InexactPartial } from "#utils";
 import type { DOMOutputSpec, Fragment, Mark, Schema } from "prosemirror-model";
 
-/**
- * @param node - The ProseMirror node.
- * @returns The specification to build a DOM node for this ProseMirror node.
- */
-export type ProseMirrorNodeOutput = (node: Node) => DOMOutputSpec;
-
-/**
- * @param mark   - The ProseMirror mark.
- * @param inline - Is the mark appearing in an inline context?
- * @returns The specification to build a DOM node for this ProseMirror mark.
- */
-
-export type ProseMirrorMarkOutput = (mark: Mark, inline: boolean) => DOMOutputSpec;
-
-export default StringSerializer;
 /**
  * A class responsible for serializing a ProseMirror document into a string of HTML.
  */
@@ -23,7 +9,7 @@ declare class StringSerializer {
    * @param nodes - The node output specs.
    * @param marks - The mark output specs.
    */
-  constructor(nodes: Record<string, ProseMirrorNodeOutput>, marks: Record<string, ProseMirrorMarkOutput>);
+  constructor(nodes: Record<string, StringSerializer.NodeOutput>, marks: Record<string, StringSerializer.MarkOutput>);
 
   /**
    * Build a serializer for the given schema.
@@ -34,13 +20,11 @@ declare class StringSerializer {
   /**
    * Create a StringNode from a ProseMirror DOMOutputSpec.
    * @param spec   - The specification.
-   * @param inline - Whether this is a block or inline node.
+   * @param inline - Whether this is a block or inline node. (default: `true`)
    * @returns An object describing the outer node, and a reference to the child node where content should be appended, if applicable.
+   * @remarks `inline` gets passed to `new StringNode`, where it has a default of `true`
    */
-  protected _specToStringNode(
-    spec: DOMOutputSpec | string,
-    inline: boolean,
-  ): { outer: StringNode; content?: StringNode };
+  protected _specToStringNode(spec: DOMOutputSpec, inline?: boolean): StringSerializer.SpecToStringNodeReturn;
 
   /**
    * Serialize a ProseMirror fragment into an HTML string.
@@ -59,9 +43,33 @@ declare class StringSerializer {
   /**
    * Convert a ProseMirror mark representation to a StringNode.
    * @param mark   - The ProseMirror mark.
-   * @param inline - Does the mark appear in an inline context?
+   * @param inline - Does the mark appear in an inline context? (default: `true`)
+   * @remarks `inline` gets passed to {@linkcode _specToStringNode}, which forwards to `new StringNode`, where it has a default of `true`
+   */
+  protected _serializeMark(mark: Mark, inline?: boolean): StringSerializer.SpecToStringNodeReturn;
+
+  #StringSerializer: true;
+}
+
+declare namespace StringSerializer {
+  /**
+   * @param node - The ProseMirror node.
+   * @returns The specification to build a DOM node for this ProseMirror node.
+   */
+  type NodeOutput = (node: Node) => DOMOutputSpec;
+
+  /**
+   * @param mark   - The ProseMirror mark.
+   * @param inline - Is the mark appearing in an inline context?
+   * @returns The specification to build a DOM node for this ProseMirror mark.
    */
-  protected _serializeMark(mark: Mark, inline: boolean): ReturnType<StringSerializer["_specToStringNode"]>;
+
+  type MarkOutput = (mark: Mark, inline: boolean) => DOMOutputSpec;
+
+  interface SpecToStringNodeReturn {
+    outer: StringNode;
+    content?: StringNode | undefined;
+  }
 }
 
 /**
@@ -70,18 +78,20 @@ declare class StringSerializer {
 declare class StringNode {
   /**
    * @param tag    - The tag name. If none is provided, this node's children will not be wrapped in an outer tag.
-   * @param attrs  - The tag attributes.
-   * @param inline - Whether the node appears inline or as a block.
+   * @param attrs  - The tag attributes. (default: `{}`)
+   * @param inline - Whether the node appears inline or as a block. (default: `true`)
    */
   constructor(tag?: string, attrs?: Record<string, string>, inline?: boolean);
 
   /**
    * The tag name.
+   * @remarks `defineProperty`'d at construction, `writable: false`
    */
   readonly tag: string | undefined;
 
   /**
    * The tag attributes.
+   * @remarks `defineProperty`'d at construction, `writable: false`
    */
   readonly attrs: Record<string, string> | undefined;
 
@@ -100,21 +110,30 @@ declare class StringNode {
   /**
    * Serialize the StringNode structure into a single string.
    * @param spaces - The number of spaces to use for indentation (maximum 10). If this value is a string,
-   *                 that string is used as indentation instead (or the first 10 characters if it is
-   *                 longer). (default: `0`)
+   * that string is used as indentation instead (or the first 10 characters if it is longer). (default: `0`)
    */
-  toString(
-    spaces?: string | number,
-    {
-      _depth,
-      _inlineParent,
-    }?: {
-      /** @internal (default: `0`) */
-      _depth?: number;
-      /** @internal (default: `false`) */
-      _inlineParent?: boolean;
-    },
-  ): string;
+  toString(spaces?: string | number, options?: StringNode.ToStringOptions): string;
+
+  #StringNode: true;
+}
+
+declare namespace StringNode {
+  /** @internal */
+  type _ToStringOptions = InexactPartial<{
+    /**
+     * @internal
+     * @defaultValue `0`
+     */
+    _depth: number;
+
+    /**
+     * @internal
+     * @defaultValue `false`
+     */
+    _inlineParent: boolean;
+  }>;
+
+  interface ToStringOptions extends _ToStringOptions {}
 }
 
-export { StringNode };
+export { StringSerializer as default, StringNode };

package/src/foundry/common/prosemirror/util.d.mts

@@ -1,7 +1,6 @@
 import type { Node, Schema, Slice } from "prosemirror-model";
-// Fixes VSC not finding it for the @link TSDoc directive.
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
 import type { StringNode } from "./string-serializer.d.mts";
+import type { InexactPartial } from "#utils";
 
 /**
  * Use the DOM and ProseMirror's DOMParser to construct a ProseMirror document state from an HTML string. This cannot be
@@ -9,6 +8,7 @@ import type { StringNode } from "./string-serializer.d.mts";
  * @param htmlString - A string of HTML.
  * @param schema     - The ProseMirror schema to use instead of the default one.
  * @returns The document node.
+ * @remarks Uses {@linkcode foundry.prosemirror.defaultSchema} if none is provided
  */
 export declare function parseHTMLString(htmlString: string, schema?: Schema): Node;
 
@@ -16,23 +16,33 @@ export declare function parseHTMLString(htmlString: string, schema?: Schema): No
  * Use the StringSerializer to convert a ProseMirror document into an HTML string. This can be used server-side.
  * @param doc     - The ProseMirror document.
  * @param options - Additional options to configure serialization behavior.
- * @returns
  */
-export declare function serializeHTMLString(
-  doc: Node,
-  options?: {
-    /** The ProseMirror schema to use instead of the default one. */
-    schema?: Schema;
-    /** The number of spaces to use for indentation. See {@link StringNode#toString} for details. */
-    spaces?: string | number;
-  },
-): string;
+declare function serializeHTMLString(doc: Node, options?: serializeHTMLString.Options): string;
 
-/**
- * @param node    - The candidate node.
- * @returns A new node to replace the candidate node, or nothing if a replacement should not be made.
- */
-export declare type ProseMirrorSliceTransformer = (node: Node) => Node | void;
+declare namespace serializeHTMLString {
+  /**
+   * Hack to make the link in Options["spaces"] work
+   * @internal
+   */
+  type _StringNode = StringNode;
+
+  /** @internal */
+  type _Options = InexactPartial<{
+    /**
+     * The ProseMirror schema to use instead of the default one.
+     * @defaultValue {@linkcode foundry.prosemirror.defaultSchema}
+     */
+    schema: Schema;
+
+    /**
+     * The number of spaces to use for indentation. See {@link _StringNode.toString | `StringNode#toString`} for details.
+     * @defaultValue `0`
+     */
+    spaces: string | number;
+  }>;
+
+  interface Options extends _Options {}
+}
 
 /**
  * Apply a transformation to some nodes in a slice, and return the new slice.
@@ -40,4 +50,14 @@ export declare type ProseMirrorSliceTransformer = (node: Node) => Node | void;
  * @param transformer - The transformation function.
  * @returns Either the original slice if no changes were made, or the newly-transformed slice.
  */
-export declare function transformSlice(slice: Slice, transformer: ProseMirrorSliceTransformer): Slice;
+declare function transformSlice(slice: Slice, transformer: transformSlice.SliceTransformer): Slice;
+
+declare namespace transformSlice {
+  /**
+   * @param node - The candidate node.
+   * @returns A new node to replace the candidate node, or nothing if a replacement should not be made.
+   */
+  type SliceTransformer = (node: Node) => Node | void;
+}
+
+export { serializeHTMLString, transformSlice };

package/src/foundry/common/utils/_module.d.mts

@@ -1,3 +1,4 @@
+import type { AnyFunction } from "#utils";
 // In Foundry itself this file contains re-exports of these other modules.
 // Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
 // While `.mts` could work, to avoid `import-x/no-unresolved` from erroring `.mjs` is used.
@@ -13,6 +14,8 @@ export { default as IterableWeakSet } from "./iterable-weak-set.mjs";
 export { default as IterableWeakMap } from "./iterable-weak-map.mjs";
 export { default as Color } from "./color.mjs";
 export { default as Semaphore } from "./semaphore.mjs";
-export { default as StringTree } from "./string-tree.mjs";
-export { default as WordTree } from "./word-tree.mjs";
 export { default as BitMask } from "./bitmask.mjs";
+export { default as WordTree } from "./word-tree.mjs";
+export { default as StringTree } from "./string-tree.mjs";
+
+export const AsyncFunction: AnyFunction;

package/src/foundry/common/utils/_types.d.mts

@@ -1 +1,28 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+// After seeing that none of these types add anything or are even exported a
+// very reasonable question may be: Why on earth does this file exist?
+//
+// Well this is the file in which Foundry defines these types. We don't house
+// them here because it has poor discoverability. The names Foundry has chosen
+// also overlaps with other existing names, such as SettingConfig vs. ClientSetting.SettingConfig
+
 export {};
+
+type LineIntersection = foundry.utils.LineIntersection;
+
+type LineCircleIntersection = foundry.utils.LineCircleIntersection;
+
+type ResolvedUUID = foundry.utils.ResolvedUUID;
+
+type IterableWeakMapHeldValue<K extends WeakKey> = foundry.utils.IterableWeakMap.HeldValue<K>;
+
+type IterableWeakMapValue<K extends WeakKey, V> = foundry.utils.IterableWeakMap.Value<K, V>;
+
+type StringTreeNode<Leaf extends object> = foundry.utils.StringTree.Node<Leaf>;
+
+type StringTreeEntryFilter<Leaf extends object> = foundry.utils.StringTree.EntryFilter<Leaf>;
+
+type WordTreeEntry<DocumentName extends foundry.abstract.Document.Type> = foundry.utils.WordTree.Entry<DocumentName>;
+
+type EmittedEventListener = foundry.utils.EventEmitterMixin.EventListener;

package/src/foundry/common/utils/bitmask.d.mts

@@ -1,16 +1,17 @@
+import type { Identity } from "#utils";
+
 declare class InternalBitMask<T extends Record<string, boolean>> extends Number {
   /**
    * Create a new BitMask instance.
-   * @param states    - An object containing valid states and their corresponding initial boolean values (default is null).
+   * @param states - An object containing valid states and their corresponding initial boolean values (default is null).
+   * @remarks
+   * @throws If the passed list of states has more than 32 keys
    */
   constructor(states?: T | null);
 
-  // a placeholder private method to help subclassing
-  #bitmask: true;
-
   /**
    * The enum associated with this structure.
-   * @readonly
+   * @remarks Foundry marks `@readonly`; the object is frozen, but the property is not
    */
   states: Readonly<{ [K in keyof T]: K }>;
 
@@ -93,7 +94,7 @@ declare class InternalBitMask<T extends Record<string, boolean>> extends Number
    * Convert value of this BitMask to object representation according to structure.
    * @returns The data represented by the bitmask.
    */
-  toObject(): Record<string, boolean>;
+  toObject(): this;
 
   /**
    * Creates a clone of this BitMask instance.
@@ -107,10 +108,13 @@ declare class InternalBitMask<T extends Record<string, boolean>> extends Number
    * @returns Shader bit mask constants generated from the states.
    */
   static generateShaderBitMaskConstants(states: string[]): string;
+
+  #BitMask: true;
 }
 
 declare namespace BitMask {
-  export type Any = InternalBitMask<Record<string, boolean>>;
+  interface Any extends InternalBitMask<Record<string, boolean>> {}
+  interface AnyConstructor extends Identity<typeof BitMask> {}
 }
 
 declare const BitMask: typeof InternalBitMask & (new (...args: any) => number);

package/src/foundry/common/utils/collection.d.mts

@@ -1,24 +1,26 @@
 // This class exists make it as sound as possible to override these parts of the class and make them
+
+import type { AnyArray, GetKey, Identity } from "#utils";
+
 // completely unrelated. It's done this way specifically to avoid situations with broken inheritance.
-declare class LenientMap<K, V> extends globalThis.Map<K, V> {
+declare class Map<K, V> extends globalThis.Map<K, V> {
   [Symbol.iterator](): any;
-  forEach(...args: any[]): any;
+  forEach(...args: AnyArray): any;
+  get(...args: AnyArray): any;
 }
 
-declare const Map: typeof LenientMap;
-
 /**
  * A reusable storage concept which blends the functionality of an Array with the efficient key-based lookup of a Map.
  * This concept is reused throughout Foundry VTT where a collection of uniquely identified elements is required.
- * @typeParam T - The type of the objects contained in the Collection
+ * @template T - The type of the objects contained in the Collection
  */
-declare class Collection<V> extends Map<string, V> {
+declare class Collection<V, Methods extends Collection.Methods.Any = Collection.Methods<V>> extends Map<string, V> {
   constructor(entries?: Iterable<readonly [string, V]> | null);
 
   /**
    * When iterating over a Collection, we should iterate over its values instead of over its entries
    */
-  [Symbol.iterator](): IterableIterator<V>;
+  [Symbol.iterator](): MapIterator<V>;
 
   /**
    * Return an Array of all the entry values in the Collection
@@ -27,7 +29,7 @@ declare class Collection<V> extends Map<string, V> {
 
   /**
    * Find an entry in the Map using an functional condition.
-   * @see {@link Array#find}
+   * @see {@link Array.find | `Array#find`}
    *
    * @param condition - The functional condition to test. Positional arguments are the value, the index of
    *                    iteration, and the collection being searched.
@@ -39,12 +41,14 @@ declare class Collection<V> extends Map<string, V> {
    * c.get("a") === c.find(entry => entry === "A"); // true
    * ```
    */
-  find<S extends V>(condition: (e: V, index: number, collection: Collection<V>) => e is S): S | undefined;
-  find(condition: (e: V, index: number, collection: Collection<V>) => boolean): V | undefined;
+  find<S extends V>(
+    /** @immediate */ condition: (e: V, index: number, collection: Collection<V>) => e is S,
+  ): S | undefined;
+  find(/** @immediate */ condition: (e: V, index: number, collection: Collection<V>) => boolean): V | undefined;
 
   /**
    * Filter the Collection, returning an Array of entries which match a functional condition.
-   * @see {@link Array#filter}
+   * @see {@link Array.filter | `Array#filter`}
    *
    * @param condition - The functional condition to test. Positional arguments are the value, the
    *                    index of iteration, and the collection being filtered.
@@ -56,12 +60,12 @@ declare class Collection<V> extends Map<string, V> {
    * let hasA = c.filters(entry => entry.slice(0) === "A");
    * ```
    */
-  filter<S extends V>(condition: (e: V, index: number, collection: Collection<V>) => e is S): S[];
-  filter(condition: (e: V, index: number, collection: Collection<V>) => boolean): V[];
+  filter<S extends V>(/** @immediate */ condition: (e: V, index: number, collection: Collection<V>) => e is S): S[];
+  filter(/** @immediate */ condition: (e: V, index: number, collection: Collection<V>) => boolean): V[];
 
   /**
    * Apply a function to each element of the collection
-   * @see Array#forEach
+   * @see {@link Array.forEach | `Array#forEach`}
    * @param fn - The function to apply to each element
    *
    * @example Apply a function to each value in the collection
@@ -70,7 +74,7 @@ declare class Collection<V> extends Map<string, V> {
    * c.forEach(e => e.active = true);
    * ```
    */
-  forEach(fn: (e: V) => void): void;
+  forEach(/** @immediate */ fn: (e: V) => void): void;
 
   /**
    * Get an element from the Collection by its key.
@@ -87,8 +91,7 @@ declare class Collection<V> extends Map<string, V> {
    * c.get("d", {strict: true}); // throws Error
    * ```
    */
-  get(key: string, { strict }: { strict: true }): V;
-  get(key: string, { strict }?: { strict?: false }): V | undefined;
+  get: Methods["get"];
 
   /**
    * Get an entry from the Collection by name.
@@ -113,18 +116,18 @@ declare class Collection<V> extends Map<string, V> {
    * Transform each element of the Collection into a new form, returning an Array of transformed values
    * @param transformer - A transformation function applied to each entry value. Positional arguments are the value, the
    *                      index of iteration, and the collection being mapped.
-   * @typeParam M       - The type of the mapped values
+   * @template M       - The type of the mapped values
    * @returns An Array of transformed values
    */
-  map<M>(transformer: (entity: V, index: number, collection: Collection<V>) => M): M[];
+  map<M>(/** @immediate */ transformer: (entity: V, index: number, collection: Collection<V>) => M): M[];
 
   /**
    * Reduce the Collection by applying an evaluator function and accumulating entries
-   * @see {@link Array#reduce}
+   * @see {@link Array.reduce | `Array#reduce`}
    * @param reducer   - A reducer function applied to each entry value. Positional arguments are the accumulator, the
    *                    value, the index of iteration, and the collection being reduced.
    * @param initial   - An initial value which accumulates with each iteration
-   * @typeParam A     - The type of the accumulator and the return value
+   * @template A     - The type of the accumulator and the return value
    * @returns The accumulated result
    *
    * @example Reduce a collection to an array of transformed values
@@ -135,30 +138,62 @@ declare class Collection<V> extends Map<string, V> {
    * }, ""); // "ABC"
    * ```
    */
-  reduce<A>(evaluator: (accumulator: A, entity: V, index: number, collection: Collection<V>) => A, initial: A): A;
+  reduce<A>(
+    /** @immediate */ evaluator: (accumulator: A, entity: V, index: number, collection: Collection<V>) => A,
+    initial: A,
+  ): A;
 
   /**
    * Test whether a condition is met by some entry in the Collection.
-   * @see Array#some
+   * @see {@link Array.some | `Array#some`}
    * @param condition - The functional condition to test. Positional arguments are the value, the index of iteration,
    *                    and the collection being tested.
    * @returns Was the test condition passed by at least one entry?
    */
-  some(condition: (e: V, index: number, collection: Collection<V>) => boolean): boolean;
+  some(/** @immediate */ condition: (e: V, index: number, collection: Collection<V>) => boolean): boolean;
 
   /**
    * Convert the Collection to a primitive array of its contents.
    * @returns An array of contained values
    */
-  toJSON(): Array<V extends { toJSON: (...args: any[]) => infer U } ? U : V>;
+  toJSON(): Array<V extends { toJSON: (...args: infer _1) => infer U } ? U : V>;
 }
 
 declare namespace Collection {
-  type AnyConstructor = typeof AnyCollection;
+  interface Any extends AnyCollection {}
+  interface AnyConstructor extends Identity<typeof AnyCollection> {}
+
+  interface GetOptions {
+    /**
+     * Throw an Error if the requested Embedded Document does not exist.
+     * @defaultValue `false`
+     */
+    strict?: boolean | undefined;
+  }
+
+  interface Methods<V> {
+    get<Options extends foundry.documents.abstract.DocumentCollection.GetOptions | undefined = undefined>(
+      key: string,
+      { strict }?: Options,
+    ): Collection.GetReturnType<V, Options>;
+  }
+
+  namespace Methods {
+    interface Any {
+      get(key: string, options?: never): unknown;
+    }
+  }
+
+  type GetReturnType<T, Options extends GetOptions | undefined> = _ApplyStrict<T, GetKey<Options, "strict", undefined>>;
+
+  /** @internal */
+  type _ApplyStrict<ConcreteDocument, Strict extends boolean | undefined> =
+    | (Strict extends false | undefined ? undefined : never)
+    | ConcreteDocument;
 }
 
-declare abstract class AnyCollection extends Collection<any> {
-  constructor(arg0: never, ...args: never[]);
+declare abstract class AnyCollection extends Collection<unknown, Collection.Methods.Any> {
+  constructor(...args: never);
 }
 
 export default Collection;

package/src/foundry/common/utils/color.d.mts

@@ -73,7 +73,7 @@ declare class InternalColor extends PatchedNumber {
   /**
    * The color represented as a linear RGB array.
    * Assumes r, g, and b are contained in the set [0, 1] and returns linear r, g, and b in the set [0, 1].
-   * {@link https://en.wikipedia.org/wiki/SRGB#Transformation}
+   * @see {@link https://en.wikipedia.org/wiki/SRGB#Transformation}
    */
   get linear(): Color.RGBColorVector;
 
@@ -110,6 +110,7 @@ declare class InternalColor extends PatchedNumber {
    * @param other  - Some other Color to mix with
    * @param weight - The mixing weight placed on this color where weight is placed on the other color
    * @returns The resulting mixed Color
+   * @remarks `weight` should be in the range [0, 1]
    */
   mix(other: Color, weight: number): Color;
 
@@ -151,7 +152,7 @@ declare class InternalColor extends PatchedNumber {
   /**
    * Iterating over a Color is equivalent to iterating over its [r,g,b] color channels.
    */
-  [Symbol.iterator](): Generator<number>;
+  [Symbol.iterator](): Generator<number, void, undefined>;
 
   /**
    * Set an rgb array with the rgb values contained in this Color class.
@@ -165,6 +166,7 @@ declare class InternalColor extends PatchedNumber {
    * @param color2 - The second color to mix.
    * @param weight - Weight of the linear interpolation.
    * @returns The resulting mixed color
+   * @remarks `weight` should be in the range [0, 1]
    */
   static mix(color1: number, color2: number, weight: number): number;
 
@@ -308,9 +310,16 @@ declare const Color: typeof InternalColor & (new (...args: any) => number);
 type Color = InternalColor & number;
 
 declare namespace Color {
+  /** @remarks Values between `0` and `1` */
   type RGBColorVector = [r: number, g: number, b: number];
+
+  /** @remarks Values between `0` and `1` */
   type RGBAColorVector = [r: number, g: number, b: number, a: number];
+
+  /** @remarks Values between `0` and `1` */
   type HSVColorVector = [h: number, s: number, v: number];
+
+  /** @remarks Values between `0` and `1` */
   type HSLColorVector = [h: number, s: number, l: number];
 
   type Source = number | RGBColorVector | string | Color;

package/src/foundry/common/utils/event-emitter.d.mts

@@ -1,12 +1,14 @@
-import type { InexactPartial, Mixin } from "fvtt-types/utils";
+import type { AnyConstructor, Coalesce, FixedInstanceType, Mixin, PhantomConstructor, InexactPartial } from "#utils";
 
 /**
  * A mixin class which implements the behavior of EventTarget.
  * This is useful in cases where a class wants EventTarget-like behavior but needs to extend some other class.
- * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget}
  */
+// ESLint doesn't like this class "only being used as a type"
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 declare class EventEmitter {
-  /** @privateRemarks All mixin classses should accept anything for its constructor. */
+  /** @privateRemarks All mixin classes should accept anything for its constructor. */
   constructor(...args: any[]);
 
   /**
@@ -16,21 +18,16 @@ declare class EventEmitter {
 
   /**
    * Add a new event listener for a certain type of event.
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener}
    * @param type     - The type of event being registered for
    * @param listener - The listener function called when the event occurs
    * @param options  - Options which configure the event listener
    */
+  // options: not null (destructured)
   addEventListener(
     type: string,
-    listener: EventEmitter.EmittedEventListener,
-    options?: InexactPartial<{
-      /**
-       * Should the event only be responded to once and then removed
-       * @defaultValue `false`
-       */
-      once: boolean;
-    }>,
+    listener: EventEmitterMixin.EventListener,
+    options?: EventEmitterMixin.AddListenerOptions,
   ): void;
 
   /**
@@ -38,25 +35,50 @@ declare class EventEmitter {
    * @param type     - The type of event being removed
    * @param listener - The listener function being removed
    */
-  removeEventListener(type: string, listener: EventEmitter.EmittedEventListener): void;
+  removeEventListener(type: string, listener: EventEmitterMixin.EventListener): void;
 
   /**
    * Dispatch an event on this target.
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent}
    * @param event - The Event to dispatch
    * @returns Was default behavior for the event prevented?
    */
   dispatchEvent(event: Event): boolean;
-}
 
-declare namespace EventEmitter {
-  type EmittedEventListener = (event: Event) => void;
+  #EventEmitter: true;
 }
 
 /**
  * Augment a base class with EventEmitter behavior.
- * @param BaseClass - Some base class augmented with event emitter functionality
+ * @param BaseClass - Some base class augmented with event emitter functionality: defaults to an anonymous empty class.
  */
-export default function EventEmitterMixin<ExtendedClass extends abstract new (...args: any[]) => any>(
-  BaseClass: ExtendedClass,
-): Mixin<typeof EventEmitter, ExtendedClass>;
+declare function EventEmitterMixin<BaseClass extends EventEmitterMixin.BaseClass | undefined = undefined>(
+  BaseClass?: BaseClass,
+): EventEmitterMixin.Mix<BaseClass>;
+
+declare namespace EventEmitterMixin {
+  interface AnyMixedConstructor extends ReturnType<typeof EventEmitterMixin<BaseClass>> {}
+  interface AnyMixed extends FixedInstanceType<AnyMixedConstructor> {}
+
+  type Mix<BaseClass extends EventEmitterMixin.BaseClass | undefined> = Mixin<
+    typeof EventEmitter,
+    Coalesce<BaseClass, PhantomConstructor>
+  >;
+
+  type BaseClass = AnyConstructor;
+
+  /** @internal */
+  type _AddListenerOptions = InexactPartial<{
+    /**
+     * Should the event only be responded to once and then removed
+     * @defaultValue `false`
+     */
+    once: boolean;
+  }>;
+
+  interface AddListenerOptions extends _AddListenerOptions {}
+
+  type EventListener = (event: Event) => void;
+}
+
+export default EventEmitterMixin;