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

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

@@ -1,31 +1,51 @@
+import type { InexactPartial } from "#utils";
+
 /**
  * A wrapper method around `fetch` that attaches an AbortController signal to the `fetch` call for clean timeouts
- * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal#aborting_a_fetch_with_timeout_or_explicit_abort
- * @param url            - The URL to make the Request to
- * @param data           - The data of the Request
- *                         (defalt: `{}`)
- * @param timeoutOptions - (default: `{}`)
- * @throws {@link HttpError}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal#aborting_a_fetch_with_timeout_or_explicit_abort}
+ * @param url     - The URL to make the Request to
+ * @param data    - The data of the Request (default: `{}`)
+ * @param options - Additional Options (default: `{}`)
+ * @throws HttpError
  */
-export declare function fetchWithTimeout(
-  url: string,
-  data?: RequestInit,
-  { timeoutMs, onTimeout }?: TimeoutOptions,
-): Promise<Response>;
+export declare function fetchWithTimeout(url: string, data?: RequestInit, options?: TimeoutOptions): Promise<Response>;
 
 /**
  * A small wrapper that automatically asks for JSON with a Timeout
- * @param url            - The URL to make the Request to
- * @param data           - The data of the Request
- *                         (defalt: `{}`)
- * @param timeoutOptions - (default: `{}`)
+ * @param url     - The URL to make the Request to
+ * @param data    - The data of the Request (default: `{}`)
+ * @param options - Additional options (default: `{}`)
  */
 export declare function fetchJsonWithTimeout(
   url: string,
   data?: RequestInit,
-  { timeoutMs, onTimeout }?: TimeoutOptions,
+  options?: TimeoutOptions,
 ): Promise<unknown>;
 
+/** @internal */
+type _TimeoutOptions = InexactPartial<{
+  /**
+   * How long to wait for a Response before cleanly aborting. If null, no timeout is applied
+   * @defaultValue `30000`
+   */
+  timeoutMs: number | null;
+
+  /**
+   * A method to invoke if and when the timeout is reached
+   * @defaultValue `() => {}`
+   */
+  onTimeout: () => void;
+}>;
+
+interface TimeoutOptions extends _TimeoutOptions {}
+
+/**
+ * Test whether a file source exists by performing a HEAD request against it
+ * @param src - The source URL or path to test
+ * @returns Does the file exist at the provided url?
+ */
+export function srcExists(src: string): Promise<boolean>;
+
 /**
  * Represents an HTTP Error when a non-OK response is returned by Fetch
  */
@@ -35,18 +55,6 @@ export declare class HttpError extends Error {
   code: number;
 
   displayMessage: string;
-}
 
-interface TimeoutOptions {
-  /**
-   * How long to wait for a Response before cleanly aborting. If null, no timeout is applied
-   * @defaultValue `30000`
-   */
-  timeoutMs?: number | undefined | null;
-
-  /**
-   * A method to invoke if and when the timeout is reached
-   * @defaultValue `() => {}`
-   */
-  onTimeout?: (() => void) | undefined;
+  override toString(): string;
 }

package/src/foundry/common/utils/iterable-weak-map.d.mts

@@ -1,20 +1,10 @@
-interface IterableWeakMapHeldValue<K extends WeakKey> {
-  /**
-   * The set to be cleaned.
-   */
-  set: Set<WeakRef<K>>;
-
-  /**
-   * The ref to remove.
-   */
-  ref: WeakRef<K>;
-}
+import type { Identity } from "#utils";
 
 /**
  * Stores a map of objects with weak references to the keys, allowing them to be garbage collected. Both keys and values
  * can be iterated over, unlike a WeakMap.
- * @typeParam K - the type of the keys contained in the IterableWeakMap
- * @typeParam V - The type of the values contained in the IterableWeakMap
+ * @template K - the type of the keys contained in the IterableWeakMap
+ * @template V - The type of the values contained in the IterableWeakMap
  */
 declare class IterableWeakMap<K extends WeakKey, V> extends WeakMap<K, V> {
   /**
@@ -22,23 +12,16 @@ declare class IterableWeakMap<K extends WeakKey, V> extends WeakMap<K, V> {
    */
   constructor(entries?: Iterable<[K, V]>);
 
-  /**
-   * Clean up the corresponding ref in the set when its value is garbage collected.
-   * @param heldValue - The value held by the finalizer.
-   */
-  static #cleanup<K extends WeakKey>(heldValue: IterableWeakMapHeldValue<K>): void;
-
   /**
    * Remove a key from the map.
    * @param key - The key to remove.
-   * @returns `true` if a key was removed, `false` otherwise.
+   * @remarks Returns `true` if a key was removed, `false` otherwise.
    */
   delete(key: K): boolean;
 
   /**
    * Retrieve a value from the map.
    * @param key - The value's key.
-   * @returns
    */
   get(key: K): V | undefined;
 
@@ -46,35 +29,65 @@ declare class IterableWeakMap<K extends WeakKey, V> extends WeakMap<K, V> {
    * Place a value in the map.
    * @param key   - The key.
    * @param value - The value.
-   * @returns
    */
   set(key: K, value: V): this;
 
+  /**
+   * Clear all values from the map.
+   */
+  clear(): void;
+
   /**
    * Enumerate the entries.
    * @returns
    */
-  [Symbol.iterator](): Generator<[K, V], void, never>;
+  [Symbol.iterator](): Generator<[K, V], void, undefined>;
 
   /**
    * Enumerate the entries.
    */
-  entries(): Generator<[K, V], void, never>;
+  entries(): Generator<[K, V], void, undefined>;
 
   /**
    * Enumerate the keys.
    */
-  keys(): Generator<K, void, never>;
+  keys(): Generator<K, void, undefined>;
 
   /**
    * Enumerate the values.
    */
-  values(): Generator<V, void, never>;
+  values(): Generator<V, void, undefined>;
 
-  /**
-   * Clear all values from the map.
-   */
-  clear(): void;
+  #IterableWeakMap: true;
+}
+
+declare namespace IterableWeakMap {
+  interface Any extends AnyIterableWeakMap {}
+  interface AnyConstructor extends Identity<typeof AnyIterableWeakMap> {}
+
+  interface HeldValue<K extends WeakKey> {
+    /**
+     * The set to be cleaned.
+     */
+    set: Set<WeakRef<K>>;
+
+    /**
+     * The ref to remove.
+     */
+    ref: WeakRef<K>;
+  }
+
+  interface Value<K extends WeakKey, V> {
+    /** The value */
+    value: V;
+
+    /** The weak ref of the key. */
+    ref: WeakRef<K>;
+  }
 }
 
 export default IterableWeakMap;
+
+declare abstract class AnyIterableWeakMap extends IterableWeakMap<WeakKey, unknown> {
+  constructor(...args: never);
+}

package/src/foundry/common/utils/iterable-weak-set.d.mts

@@ -1,47 +1,60 @@
+import type { Identity } from "#utils";
+
 /**
  * Stores a set of objects with weak references to them, allowing them to be garbage collected. Can be iterated over,
  * unlike a WeakSet.
- * @typeParam T - The type of the objects contained in the WeakSet
+ * @template K - The type of the objects contained in the WeakSet
  */
-declare class IterableWeakSet<T extends WeakKey> extends WeakSet<T> {
+declare class IterableWeakSet<K extends WeakKey> extends WeakSet<K> {
   /**
    * @param entries - The initial entries.
    */
-  constructor(entries?: Iterable<T>);
+  constructor(entries?: Iterable<K>);
 
   /**
    * Enumerate the values.
    */
-  [Symbol.iterator](): Generator<T, void, never>;
+  [Symbol.iterator](): Generator<K, void, undefined>;
 
   /**
    * Add a value to the set.
    * @param value - The value to add.
    */
-  add(value: T): this;
+  add(value: K): this;
 
   /**
    * Delete a value from the set.
    * @param value - The value to delete.
    */
-  delete(value: T): boolean;
+  delete(value: K): boolean;
 
   /**
    * Whether this set contains the given value.
    * @param value - The value to test.
    * @returns
    */
-  has(value: T): boolean;
+  has(value: K): boolean;
 
   /**
    * Enumerate the collection.
    */
-  values(): Generator<T, void, never>;
+  values(): Generator<K, void, undefined>;
 
   /**
    * Clear all values from the set.
    */
   clear(): void;
+
+  #IterableWeakSet: true;
+}
+
+declare namespace IterableWeakSet {
+  interface Any extends AnyIterableWeakSet {}
+  interface AnyConstructor extends Identity<typeof AnyIterableWeakSet> {}
 }
 
 export default IterableWeakSet;
+
+declare abstract class AnyIterableWeakSet extends IterableWeakSet<WeakKey> {
+  constructor(...args: never);
+}

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

@@ -1,42 +1,49 @@
+import type { InexactPartial } from "#utils";
 import type { COMPATIBILITY_MODES } from "../constants.d.mts";
 
 /**
  * Log a compatibility warning which is filtered based on the client's defined compatibility settings.
  * @param message - The original warning or error message
  * @param options - Additional options which customize logging (default: `{}`)
- * @throws        - An Error if the mode is ERROR
+ * @throws An Error if the mode is ERROR
  */
 export declare function logCompatibilityWarning(message: string, options?: LogCompatibilityWarningOptions): void;
-export interface LogCompatibilityWarningOptions {
+
+/** @internal */
+type _LogCompatibilityWarningOptions = InexactPartial<{
   /**
    * A logging level in COMPATIBILITY_MODES which overrides the configured default
+   * @remarks Defaults to {@linkcode CONFIG.compatibility.mode} if `CONFIG.compatibility` exists,
+   * falls back to {@linkcode COMPATIBILITY_MODES.WARNING} otherwise
    */
-  mode?: COMPATIBILITY_MODES;
+  mode: COMPATIBILITY_MODES;
 
   /**
    * A version identifier since which a change was made
    */
-  since?: number | string;
+  since: number | string;
 
   /**
    * A version identifier until which a change remains supported
    */
-  until?: number | string;
+  until: number | string;
 
   /**
    * Additional details to append to the logged message
    */
-  details?: string;
+  details: string;
 
   /**
    * Include the message stack trace
    * @defaultValue `true`
    */
-  stack?: boolean;
+  stack: boolean;
 
   /**
    * Log this message only once?
    * @defaultValue `false`
    */
-  once?: boolean;
-}
+  once: boolean;
+}>;
+
+export interface LogCompatibilityWarningOptions extends _LogCompatibilityWarningOptions {}

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

@@ -1,16 +1,19 @@
+import type { Identity } from "#utils";
+
 /**
  * A simple Semaphore implementation which provides a limited queue for ensuring proper concurrency.
  *
- * @example Some async function that takes time to execute
- * ```typescript
- * function fn(x: string): Promise<string> {
+ * @example Using a Semaphore
+ * ```ts
+ * // Some async function that takes time to execute
+ * function fn(x) {
  *   return new Promise(resolve => {
  *     setTimeout(() => {
  *       console.log(x);
  *       resolve(x);
- *     }, 1000));
- *   }
- * };
+ *     }, 1000);
+ *   });
+ * }
  *
  * // Create a Semaphore and add many concurrent tasks
  * const semaphore = new Semaphore(1);
@@ -31,22 +34,6 @@ declare class Semaphore {
    */
   max: number;
 
-  /**
-   * A queue of pending function signatures
-   * @defaultValue `[]`
-   * @internal
-   * @remarks The first element of an element of `_queue` is always a function and the rest of the elements are
-   * parameters to be passed to that function.
-   */
-  _queue: Array<Array<unknown>>;
-
-  /**
-   * The number of tasks which are currently underway
-   * @defaultValue `0`
-   * @internal
-   */
-  protected _active: number;
-
   /**
    * The number of pending tasks remaining in the queue
    */
@@ -70,13 +57,16 @@ declare class Semaphore {
    */
   clear(): void;
 
-  /**
-   * Attempt to perform a task from the queue.
-   * If all workers are busy, do nothing.
-   * If successful, try again.
-   * @internal
-   */
-  protected _try(): Promise<false | void>;
+  #Semaphore: true;
+}
+
+declare namespace Semaphore {
+  interface Any extends AnySemaphore {}
+  interface AnyConstructor extends Identity<typeof AnySemaphore> {}
 }
 
 export default Semaphore;
+
+declare abstract class AnySemaphore extends Semaphore {
+  constructor(...args: never);
+}

package/src/foundry/common/utils/string-tree.d.mts

@@ -1,18 +1,16 @@
-import type { InexactPartial } from "fvtt-types/utils";
+import type { AnyObject, Identity, InexactPartial } from "#utils";
+
+/** @privateRemarks Getters like {@linkcode StringTree.leaves} are not allowed to return `unique symbol` directly */
+declare const _leavesSymbol: unique symbol;
 
 /**
  * A data structure representing a tree of string nodes with arbitrary object leaves.
  */
-declare class StringTree<EntryType> {
+declare class StringTree<Leaf extends object = AnyObject, Key = string[]> {
   /**
    * The key symbol that stores the leaves of any given node.
    */
-  // replaced the getter definition with a static property so that
-  //    it can be referenced as part of the StringTreeNode interface
-  // static get leaves(): symbol;
-  static readonly leaves: unique symbol;
-
-  static readonly #leaves: unique symbol;
+  static get leaves(): typeof _leavesSymbol;
 
   /**
    * Insert an entry into the tree.
@@ -20,7 +18,7 @@ declare class StringTree<EntryType> {
    * @param entry    - The entry to store.
    * @returns   The node the entry was added to.
    */
-  addLeaf(strings: string[], entry: EntryType): StringTree.StringTreeNode;
+  addLeaf(strings: Key, entry: Leaf): StringTree.Node<Leaf>;
 
   /**
    * Traverse the tree along the given string path and return any entries reachable from the node.
@@ -28,68 +26,79 @@ declare class StringTree<EntryType> {
    * @param options         - Additional options to configure behaviour.
    * @returns    The reachable entries
    */
-  lookup(
-    strings: string[],
-    options?: InexactPartial<{
-      /** The maximum number of items to retrieve. */
-      limit: number;
-      /** A filter function to apply to each candidate entry. */
-      filterEntries?: StringTree.StringTreeEntryFilter | undefined;
-    }>,
-  ): StringTree.StringTreeNode[];
+  lookup(strings: Key, options?: StringTree.LookupOptions<Leaf>): Leaf[];
 
   /**
    * Returns the node at the given path through the tree.
-   * @param strings                     - The string path to the desired node.
-   * @param options                     - Additional options to configure behaviour.
+   * @param strings - The string path to the desired node.
+   * @param options - Additional options to configure behaviour.
    * @returns The node at the path, if found
    */
-  nodeAtPrefix(
-    strings: string[],
-    options?: InexactPartial<{
-      /**
-       * Only return the most recently visited node that has
-       * leaves, otherwise return the exact node at the prefix,
-       * if it exists. Defaults to false.
-       */
-      hasLeaves: boolean;
-    }>,
-  ): StringTree.StringTreeNode | void;
+  nodeAtPrefix(strings: Key, options?: StringTree.NodeAtPrefixOptions): StringTree.Node<Leaf> | undefined;
 
   /**
    * Perform a breadth-first search starting from the given node and retrieving any entries reachable from that node,
    * until we reach the limit.
-   * @param node            - The starting node.
-   * @param entries         - The accumulated entries.
-   * @param queue           - The working queue of nodes to search.
-   * @param options         - Additional options to configure behaviour.
+   * @param node    - The starting node.
+   * @param entries - The accumulated entries.
+   * @param queue   - The working queue of nodes to search.
+   * @param options - Additional options to configure behaviour.
    */
   protected _breadthFirstSearch(
-    node: StringTree.StringTreeNode,
-    entries: EntryType[],
-    queue: StringTree.StringTreeNode[],
-    options?: InexactPartial<{
-      /** The maximum number of entries to retrieve before stopping. */
-      limit: number;
-    }>,
+    node: StringTree.Node<Leaf>,
+    entries: Leaf[],
+    queue: StringTree.Node<Leaf>[],
+    options?: StringTree.BreadthFirstSearchOptions<Leaf>,
   ): void;
+
+  #StringTree: true;
 }
 
 declare namespace StringTree {
+  interface Any extends AnyStringTree {}
+  interface AnyConstructor extends Identity<typeof AnyStringTree> {}
+
   /**
    * A string tree node consists of zero-or-more string keys, and a leaves property that contains any objects that
    * terminate at the current node.
    */
-  interface StringTreeNode {
-    [StringTree.leaves]: Record<string, unknown>[];
-    [key: string]: StringTreeNode;
+  interface Node<Leaf extends object> {
+    [StringTree.leaves]: Leaf[];
+    [key: string]: Node<Leaf>;
   }
 
   /**
-   * @param entry   - The entry to filter.
+   * @template Leaf - The leaf type of this StringTree
+   * @param entry - The entry to filter.
    * @returns Whether the entry should be included in the result set.
    */
-  type StringTreeEntryFilter = (entry: unknown) => boolean;
+  type EntryFilter<Leaf extends object> = (entry: Leaf) => boolean;
+
+  /** @internal */
+  type _SearchOptions<Leaf extends object> = InexactPartial<{
+    /** The maximum number of items to retrieve. */
+    limit: number;
+
+    /** A filter function to apply to each candidate entry. */
+    filterEntries: StringTree.EntryFilter<Leaf>;
+  }>;
+
+  interface LookupOptions<Leaf extends object> extends _SearchOptions<Leaf> {}
+
+  interface NodeAtPrefixOptions {
+    /**
+     * Only return the most recently visited node that has leaves,
+     * otherwise return the exact node at the prefix, if it exists.
+     * @defaultValue `false`
+     */
+    hasLeaves?: boolean | undefined;
+  }
+
+  interface BreadthFirstSearchOptions<Leaf extends object> extends _SearchOptions<Leaf> {}
 }
 
 export default StringTree;
+
+declare abstract class AnyStringTree extends StringTree<object, string[]> {
+  constructor(...args: never);
+}

package/src/foundry/common/utils/word-tree.d.mts

@@ -1,66 +1,90 @@
-import type { InexactPartial } from "fvtt-types/utils";
-import type StringTree from "./string-tree.d.mts";
+import type { Identity, InexactPartial } from "#utils";
+import type { StringTree } from "./_module.d.mts";
+import type { Document } from "#common/abstract/_module.d.mts";
 
 /**
  * A data structure for quickly retrieving objects by a string prefix.
  * Note that this works well for languages with alphabets (latin, cyrillic, korean, etc.), but may need more nuanced
  * handling for languages that compose characters and letters.
  */
-declare class WordTree extends StringTree<WordTree.WordTreeEntry> {
+declare class WordTree<DocumentName extends Document.Type, Key = string> extends StringTree<
+  WordTree.Entry<DocumentName>,
+  Key
+> {
   /**
    * Insert an entry into the tree.
-   * @param string    - The string key for the entry.
-   * @param entry     - The entry to store.
-   * @returns         The node the entry was added to.
+   * @param string - The string key for the entry.
+   * @param entry - The entry to store.
+   * @returns The node the entry was added to.
    */
-  addLeaf(string: string, entry: WordTree.WordTreeEntry): StringTree.StringTreeNode;
-  addLeaf(strings: string[], entry: any): StringTree.StringTreeNode;
+  addLeaf(key: Key, entry: WordTree.Entry<DocumentName>): WordTree.EntryNode<DocumentName>;
 
   /**
    * Return entries that match the given string prefix.
-   * @param prefix              - The prefix.
-   * @param options             - Additional options to configure behaviour.
-   * @returns                   A number of entries that have the given prefix.
+   * @param prefix  - The prefix.
+   * @param options - Additional options to configure behaviour.
+   * @returns A number of entries that have the given prefix.
    */
-  lookup(
-    prefix: string,
-    options?: InexactPartial<{
-      /**
-       * The maximum number of items to retrieve. It is important
-       * to set this value as very short prefixes will naturally match large numbers
-       * of entries.
-       * (default: `10`)
-       */
-      limit: number;
-      /** A filter function to apply to each candidate entry. */
-      filterEntries?: StringTree.StringTreeEntryFilter | undefined;
-    }>,
-  ): WordTree.WordTreeEntry[];
-  lookup(strings: string[], options?: InexactPartial<{ limit: number }>): StringTree.StringTreeNode[];
+  lookup(prefix: Key, options?: WordTree.LookupOptions<DocumentName>): WordTree.Entry<DocumentName>[];
 
   /**
    * Returns the node at the given prefix.
-   * @param prefix        - The prefix.
+   * @param prefix - The prefix.
    * @returns The node
+   * @remarks Calls super with no way to provide options, meaning `undefined` is never allow
    */
-  nodeAtPrefix(strings: string[], options?: InexactPartial<{ hasLeaves: boolean }>): StringTree.StringTreeNode | void;
-  nodeAtPrefix(prefix: string): WordTree.WordTreeEntry;
+  nodeAtPrefix(prefix: Key): WordTree.EntryNode<DocumentName> | undefined;
 }
 
 declare namespace WordTree {
+  interface Any extends AnyWordTree {}
+  interface AnyConstructor extends Identity<typeof AnyWordTree> {}
+
+  /** @internal */
+  type _LookupOptions = InexactPartial<{
+    /**
+     * The maximum number of items to retrieve. It is important to set this value
+     * as very short prefixes will naturally match large numbers of entries.
+     * @defaultValue `10`
+     */
+    limit: number;
+  }>;
+
+  interface LookupOptions<DocumentName extends Document.Type>
+    extends Omit<StringTree.LookupOptions<Entry<DocumentName>>, "limit">,
+      _LookupOptions {}
+
   /**
    * A leaf entry in the tree.
    */
-  interface WordTreeEntry {
+  interface Entry<DocumentName extends Document.Type> {
     /** An object that this entry represents. */
-    entry: foundry.abstract.Document.Any;
+    // TODO(LukeAbby): This appears to be possible to be a compendium index entry.
+    entry: Document.ImplementationFor<DocumentName>;
+
     /** The document type. */
-    documentName: string;
+    documentName: DocumentName;
+
     /** The document's UUID. */
     uuid: string;
+
     /** The (optional) pack ID. */
     pack?: string;
   }
+
+  namespace Entry {
+    type Any = Entry<Document.Type>;
+  }
+
+  type EntryNode<DocumentName extends Document.Type> = StringTree.Node<Entry<DocumentName>>;
+
+  namespace EntryNode {
+    type Any = WordTree.EntryNode<Document.Type>;
+  }
 }
 
 export default WordTree;
+
+declare abstract class AnyWordTree extends WordTree<Document.Type, string> {
+  constructor(...args: never);
+}