@league-of-foundry-developers/foundry-vtt-types 9.280.0 → 12.331.1-beta

package/src/foundry/client/data/collections/compendium-collection.d.mts

@@ -0,0 +1,504 @@
+import type { DeepPartial, EmptyObject, InexactPartial } from "../../../../types/utils.d.mts";
+import type {
+  DatabaseCreateOperation,
+  DatabaseDeleteOperation,
+  DatabaseUpdateOperation,
+} from "../../../common/abstract/_types.d.mts";
+import type Document from "../../../common/abstract/document.d.mts";
+import type { DirectoryCollectionMixin_DocumentCollection_Interface } from "../abstract/directory-collection-mixin.d.mts";
+
+declare const DirectoryCollectionMixin_DocumentCollection: DirectoryCollectionMixin_DocumentCollection_Interface;
+
+declare global {
+  interface ManageCompendiumRequest extends SocketRequest {
+    /**
+     * The request action.
+     */
+    action: string;
+
+    /**
+     * The compendium creation data, or the ID of the compendium to delete.
+     */
+    data: PackageCompendiumData | string;
+
+    /**
+     * Additional options.
+     */
+    options?: Record<string, unknown>;
+  }
+
+  // @ts-expect-error Bad inheritance
+  interface ManageCompendiumResponse extends SocketResponse {
+    /**
+     * The original request.
+     */
+    request: ManageCompendiumRequest;
+
+    /**
+     * The compendium creation data, or the collection name of the deleted compendium.
+     */
+    result: PackageCompendiumData | string;
+  }
+
+  /**
+   * A collection of Document objects contained within a specific compendium pack.
+   * Each Compendium pack has its own associated instance of the CompendiumCollection class which contains its contents.
+   *
+   * @see {@link Game#packs}
+   */
+  class CompendiumCollection<
+    T extends CompendiumCollection.Metadata,
+  > extends DirectoryCollectionMixin_DocumentCollection<DocumentClassForCompendiumMetadata<T>, T["name"]> {
+    /** @param metadata - The compendium metadata, an object provided by game.data */
+    constructor(metadata: T);
+
+    /** The compendium metadata which defines the compendium content and location */
+    metadata: T;
+
+    /**  A subsidiary collection which contains the more minimal index of the pack */
+    index: IndexTypeForMetadata<T>;
+
+    /**
+     * A debounced function which will clear the contents of the Compendium pack if it is not accessed frequently.
+     * @internal
+     */
+    _flush: () => void;
+
+    /**
+     * The amount of time that Document instances within this CompendiumCollection are held in memory.
+     * Accessing the contents of the Compendium pack extends the duration of this lifetime.
+     * @defaultValue `300`
+     */
+    static CACHE_LIFETIME_SECONDS: number;
+
+    /**
+     * The named game setting which contains Compendium configurations.
+     */
+    static CONFIG_SETTING: "compendiumConfiguration";
+
+    /** The canonical Compendium name - comprised of the originating package and the pack name */
+    get collection(): this["metadata"]["id"];
+
+    /** The banner image for this Compendium pack, or the default image for the pack type if no image is set. */
+    get banner(): string | null | void;
+
+    /**
+     * A reference to the Application class which provides an interface to interact with this compendium content.
+     * @defaultValue `Compendium`
+     */
+    applicationClass: typeof Application;
+
+    /**
+     * A subsidiary collection which contains the folders within the pack
+     */
+    get folders(): CompendiumFolderCollection;
+
+    /**
+     * @remarks 1 less than in-world
+     * @defaultValue `CONST.FOLDER_MAX_DEPTH - 1`
+     */
+    get maxFolderDepth(): number;
+
+    /**
+     * Get the Folder that this Compendium is displayed within
+     */
+    get folder(): (Folder.ConfiguredInstance & { type: "Compendium" }) | null;
+
+    /**
+     * Assign this CompendiumCollection to be organized within a specific Folder.
+     * @param folder - The desired Folder within the World or null to clear the folder
+     * @returns A promise which resolves once the transaction is complete
+     */
+    setFolder(folder: Folder | string | null): Promise<void>;
+
+    /**
+     * Get the sort order for this Compendium
+     */
+    get sort(): number;
+
+    protected override _getVisibleTreeContents(): DocumentInstanceForCompendiumMetadata<T>[];
+
+    static _sortStandard(a: number, b: number): number;
+
+    /** Access the compendium configuration data for this pack */
+    get config(): CompendiumCollection.Configuration | EmptyObject;
+
+    get documentName(): this["metadata"]["type"];
+
+    /** Track whether the Compendium Collection is locked for editing */
+    get locked(): boolean;
+
+    /**
+     * The visibility configuration of this compendium pack.
+     * A value in CONST.USER_ROLES
+     * */
+    get ownership(): foundry.packages.BasePackage.OwnershipRecord;
+
+    /** Is this Compendium pack visible to the current game User? */
+    get visible(): boolean;
+
+    /** A convenience reference to the label which should be used as the title for the Compendium pack. */
+    get title(): string;
+
+    /**
+     * The index fields which should be loaded for this compendium pack
+     * @remarks Contained elements are a concatenation of the document's `metadata.compendiumIndexFields` as well as CONFIG
+     */
+    get indexFields(): Set<string>;
+
+    /**
+     * Has this Compendium pack been fully indexed?
+     * @defaultValue `false`
+     */
+    get indexed(): boolean;
+
+    get(
+      key: string,
+      options?: InexactPartial<{
+        /**
+         * Throw an Error if the requested Embedded Document does not exist.
+         * @defaultValue `false`
+         */
+        strict: false;
+        /**
+         * Allow retrieving an invalid Embedded Document.
+         * @defaultValue `false`
+         */
+        invalid: false;
+      }>,
+    ): Document.Stored<DocumentInstanceForCompendiumMetadata<T>> | undefined;
+    get(
+      key: string,
+      options: { strict: true; invalid?: false },
+    ): Document.Stored<DocumentInstanceForCompendiumMetadata<T>>;
+    get(key: string, options: { strict?: boolean; invalid: true }): unknown;
+
+    set(id: string, document: Document.Stored<DocumentInstanceForCompendiumMetadata<T>>): this;
+
+    delete: (id: string) => boolean;
+
+    clear: () => void;
+
+    /**
+     * Load the Compendium index and cache it as the keys and values of the Collection.
+     * @param options - Options which customize how the index is created
+     */
+    getIndex(options?: CompendiumCollection.GetIndexOptions<T>): Promise<this["index"]>;
+
+    /**
+     * Get a single Document from this Compendium by ID.
+     * The document may already be locally cached, otherwise it is retrieved from the server.
+     * @param id -  The requested Document id
+     * @returns The retrieved Document instance
+     */
+    getDocument(id: string): Promise<Document.Stored<DocumentInstanceForCompendiumMetadata<T>> | undefined | null>;
+
+    /**
+     * Load multiple documents from the Compendium pack using a provided query object.
+     * @param query - A database query used to retrieve documents from the underlying database
+     *                default: `{}`
+     * @returns The retrieved Document instances
+     *
+     * @example Get Documents that match the given value only.
+     * ```js
+     * await pack.getDocuments({ type: "weapon" });
+     * ```
+     *
+     * @example Get several Documents by their IDs.
+     * ```js
+     * await pack.getDocuments({ _id__in: arrayOfIds });
+     * ```
+     *
+     * @example Get Documents by their sub-types.
+     * ```js
+     * await pack.getDocuments({ type__in: ["weapon", "armor"] });
+     * ```
+     */
+    getDocuments(query?: Record<string, unknown>): Promise<Document.Stored<DocumentInstanceForCompendiumMetadata<T>>[]>;
+
+    /**
+     * Get the ownership level that a User has for this Compendium pack.
+     * @param user - The user being tested
+     * @returns The ownership level in CONST.DOCUMENT_OWNERSHIP_LEVELS
+     */
+    getUserLevel(user?: User): foundry.CONST.DOCUMENT_OWNERSHIP_LEVELS;
+
+    /**
+     * Test whether a certain User has a requested permission level (or greater) over the Compendium pack
+     * @param user       - The User being tested
+     * @param permission - The permission level from DOCUMENT_OWNERSHIP_LEVELS to test
+     * @param options    - Additional options involved in the permission test
+     * @returns Does the user have this permission level over the Compendium pack?
+     */
+    testUserPermission(
+      user: User,
+      permission: string | number,
+      options?: InexactPartial<{
+        /**
+         * Require the exact permission level requested?
+         * @defaultValue `false`
+         */
+        exact: boolean;
+      }>,
+    ): boolean;
+
+    /**
+     * Import a Document into this Compendium Collection.
+     * @param document - The existing Document you wish to import
+     * @param options  - Additional options which modify how the data is imported. See {@link ClientDocument#toCompendium}
+     *                   (default: `{}`)
+     * @returns The imported Document instance
+     */
+    importDocument(
+      document: DocumentInstanceForCompendiumMetadata<T>,
+      options?: InexactPartial<ClientDocument.CompendiumExportOptions>,
+    ): Promise<Document.Stored<DocumentInstanceForCompendiumMetadata<T>> | undefined>;
+
+    /**
+     * Import a Folder into this Compendium Collection.
+     * @param folder  - The existing Folder you wish to import
+     * @param options - Additional options which modify how the data is imported.
+     */
+    importFolder(
+      folder: Folder,
+      options?: InexactPartial<{
+        /**
+         * Import any parent folders which are not already present in the Compendium
+         * @defaultValue `true`
+         */
+        importParents: boolean;
+      }>,
+    ): Promise<void>;
+
+    /**
+     * Import an array of Folders into this Compendium Collection.
+     * @param folders - The existing Folders you wish to import
+     * @param options - Additional options which modify how the data is imported.
+     */
+    importFolders(
+      folders: Folder[],
+      options?: InexactPartial<{
+        /**
+         * Import any parent folders which are not already present in the Compendium
+         * @defaultValue `true`
+         */
+        importParents: boolean;
+      }>,
+    ): Promise<void>;
+
+    /**
+     * Fully import the contents of a Compendium pack into a World folder.
+     * @param options    - Options which modify the import operation. Additional options are forwarded to
+     *                     {@link WorldCollection#fromCompendium} and {@link Document.createDocuments}
+     *                     (default: `{}`)
+     * @returns The imported Documents, now existing within the World
+     */
+    importAll(
+      options?: InexactPartial<
+        {
+          /**
+           * An existing Folder _id to use.
+           * @defaultValue `null`
+           * */
+          folderId: string | null;
+          /**
+           * A new Folder name to create.
+           * @defaultValue `""`
+           * */
+          folderName: string;
+        } & Document.OnCreateOptions<this["metadata"]["type"]> &
+          WorldCollection.FromCompendiumOptions
+      >,
+    ): Promise<Document.Stored<DocumentInstanceForCompendiumMetadata<T>>[]>;
+
+    /**
+     * Provide a dialog form that prompts the user to import the full contents of a Compendium pack into the World.
+     * @param options - Additional options passed to the Dialog.confirm method
+     *                  (default: `{}`)
+     * @returns A promise which resolves in the following ways: an array of imported
+     *          Documents if the "yes" button was pressed, false if the "no" button was pressed, or
+     *          null if the dialog was closed without making a choice.
+     */
+    importDialog(
+      options?: DialogOptions,
+    ): Promise<Document.Stored<DocumentInstanceForCompendiumMetadata<T>>[] | null | false>;
+
+    /**
+     * Add a Document to the index, capturing it's relevant index attributes
+     * @param document -The document to index
+     */
+    indexDocument(document: Document.Stored<DocumentInstanceForCompendiumMetadata<T>>): void;
+
+    /**
+     * Prompt the gamemaster with a dialog to configure ownership of this Compendium pack.
+     * @returns The configured ownership for the pack
+     */
+    configureOwnershipDialog(): Promise<foundry.packages.BasePackage.OwnershipRecord>;
+
+    /**
+     * Activate the Socket event listeners used to receive responses to compendium management events.
+     * @param socket - The active game socket.
+     * @internal
+     */
+    protected static _activateSocketListeners(socket: Game["socket"]): void;
+
+    /**
+     * Create a new Compendium Collection using provided metadata.
+     * @param metadata - The compendium metadata used to create the new pack
+     * @param options - Additional options which modify the Compendium creation request
+     *                  default `{}`
+     */
+    static createCompendium<T extends CompendiumCollection.Metadata>(
+      metadata: T,
+      options?: Document.OnCreateOptions<T["type"]>,
+    ): Promise<CompendiumCollection<T>>;
+
+    /**
+     * Generate a UUID for a given primary document ID within this Compendium pack
+     * @param id - The document ID to generate a UUID for
+     * @returns The generated UUID, in the form of "Compendium.<collection>.<documentName>.<id>"
+     */
+    getUuid(id: string): string;
+
+    /**
+     * Assign configuration metadata settings to the compendium pack
+     * @param configuration - The object of compendium settings to define
+     *                        (default: `{}`)
+     * @returns A Promise which resolves once the setting is updated
+     */
+    configure(
+      configuration?: InexactPartial<CompendiumCollection.Configuration>,
+    ): Promise<CompendiumCollection.Configuration>;
+
+    /**
+     * Delete an existing world-level Compendium Collection.
+     * This action may only be performed for world-level packs by a Gamemaster User.
+     */
+    deleteCompendium(): Promise<this>;
+
+    /**
+     * Duplicate a compendium pack to the current World.
+     * @param label - A new Compendium label
+     */
+    duplicateCompendium({ label }?: { label?: string | undefined }): Promise<this>;
+
+    /**
+     * Migrate a compendium pack.
+     * This operation re-saves all documents within the compendium pack to disk, applying the current data model.
+     * If the document type has system data, the latest system data template will also be applied to all documents.
+     */
+    migrate(): Promise<this>;
+
+    override updateAll(
+      transformation:
+        | DeepPartial<DocumentInstanceForCompendiumMetadata<T>["_source"]>
+        | ((
+            doc: Document.Stored<DocumentInstanceForCompendiumMetadata<T>>,
+          ) => DeepPartial<DocumentInstanceForCompendiumMetadata<T>["_source"]>),
+      condition?: ((obj: Document.Stored<DocumentInstanceForCompendiumMetadata<T>>) => boolean) | null,
+      options?: Document.OnUpdateOptions<this["metadata"]["type"]>,
+    ): ReturnType<this["documentClass"]["updateDocuments"]>;
+
+    /**
+     * Follow-up actions taken when Documents within this Compendium pack are modified
+     * @internal
+     */
+    _onModifyContents(
+      action: "create",
+      documents: ClientDocument[],
+      result: Record<string, unknown>[],
+      operation: DatabaseCreateOperation<InstanceType<DocumentClassForCompendiumMetadata<T>>>,
+      user: User,
+    ): void;
+    _onModifyContents(
+      action: "update",
+      documents: ClientDocument[],
+      result: Record<string, unknown>[],
+      operation: DatabaseUpdateOperation<InstanceType<DocumentClassForCompendiumMetadata<T>>>,
+      user: User,
+    ): void;
+    _onModifyContents(
+      action: "delete",
+      documents: ClientDocument[],
+      result: string[],
+      operation: DatabaseDeleteOperation,
+      user: User,
+    ): void;
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks `"CompendiumCollection#private is deprecated in favor of the new CompendiumCollection#ownership, CompendiumCollection#getUserLevel, CompendiumCollection#visible properties"`
+     */
+    get private(): boolean;
+
+    /**
+     * @deprecated since v11, will be removed in v13
+     * @remarks `"CompendiumCollection#isOpen is deprecated and will be removed in V13"`
+     */
+    get isOpen(): boolean;
+  }
+
+  namespace CompendiumCollection {
+    type Any = CompendiumCollection<any>;
+
+    interface Configuration {
+      ownership: foundry.packages.BasePackage.OwnershipRecord;
+      locked: boolean;
+    }
+    interface Metadata {
+      type: foundry.CONST.COMPENDIUM_DOCUMENT_TYPES;
+      name: string;
+      label: string;
+      path: string;
+      private: boolean;
+      package: string;
+      system?: string;
+      /** Added by PackageCompendiumPacks#initialize */
+      id: string;
+      packageType: string;
+      packageName: string;
+    }
+
+    interface GetIndexOptions<T extends CompendiumCollection.Metadata> {
+      /**
+       * An array of fields to return as part of the index
+       * @defaultValue `[]`
+       */
+      fields?: (keyof DocumentInstanceForCompendiumMetadata<T>["_source"])[];
+    }
+
+    // TODO: Improve automatic index properties based on document type
+    type IndexEntry<T extends CompendiumCollection.Metadata> = { _id: string; uuid: string } & DeepPartial<
+      DocumentInstanceForCompendiumMetadata<T>["_source"]
+    >;
+  }
+}
+
+interface ImportAllOptions {
+  /**
+   * An existing Folder _id to use.
+   * @defaultValue `null`
+   * */
+  folderId?: string | null | undefined;
+  /**
+   * A new Folder name to create.
+   * @defaultValue `""`
+   * */
+  folderName?: string | undefined;
+  /**
+   * Additional options forwarded to {@link WorldCollection#fromCompendium} and {@link Document.createDocuments}
+   * @defaultValue `{}`
+   */
+  options?: (Document.ModificationContext<Document.Any | null> & WorldCollection.FromCompendiumOptions) | undefined;
+}
+
+type DocumentClassForCompendiumMetadata<T extends CompendiumCollection.Metadata> = Document.ConfiguredClassForName<
+  T["type"]
+>;
+
+type DocumentInstanceForCompendiumMetadata<T extends CompendiumCollection.Metadata> =
+  Document.ConfiguredInstanceForName<T["type"]>;
+
+type IndexTypeForMetadata<T extends CompendiumCollection.Metadata> = foundry.utils.Collection<
+  CompendiumCollection.IndexEntry<T>
+>;

package/src/foundry/client/data/collections/compendium-folders.d.mts

@@ -0,0 +1,13 @@
+declare global {
+  class CompendiumFolderCollection extends DocumentCollection<typeof Folder, "Folders"> {
+    constructor(pack: CompendiumPacks, data: Folder["_source"][]);
+
+    pack: CompendiumPacks;
+
+    get documentName(): "Folder";
+
+    override render(force?: boolean, options?: ApplicationOptions): void;
+  }
+}
+
+export {};

package/src/foundry/client/data/collections/compendium-packs.d.mts

@@ -0,0 +1,27 @@
+import type { DirectoryCollectionMixin_Collection_Interface } from "../abstract/directory-collection-mixin.d.mts";
+
+declare const DirectoryCollectionMixin_Collection: DirectoryCollectionMixin_Collection_Interface;
+
+declare global {
+  class CompendiumPacks extends DirectoryCollectionMixin_Collection {
+    /**
+     * Get a Collection of Folders which contain Compendium Packs
+     */
+    get folders(): Collection<Folder>;
+
+    protected override _getVisibleTreeContents(): CompendiumCollection<CompendiumCollection.Metadata>[];
+
+    protected static _sortAlphabetical(
+      a: CompendiumPacks.AlphabeticalSortEntry,
+      b: CompendiumPacks.AlphabeticalSortEntry,
+    ): number;
+  }
+
+  namespace CompendiumPacks {
+    interface AlphabeticalSortEntry extends DirectoryCollection.AlphabeticalSortEntry {
+      metadata?: {
+        label: string;
+      };
+    }
+  }
+}

package/src/foundry/client/data/collections/fog.d.mts

@@ -0,0 +1,17 @@
+export {};
+
+declare global {
+  /**
+   * The singleton collection of FogExploration documents which exist within the active World.
+   * @see {@link FogExploration} The FogExploration document
+   */
+  class FogExplorations extends WorldCollection<typeof foundry.documents.BaseFogExploration, "FogExplorations"> {
+    static documentName: "FogExploration";
+
+    /**
+     * Activate Socket event listeners to handle for fog resets
+     * @param socket - The active web socket connection
+     */
+    static _activateSocketListeners(socket: Game["socket"]): void;
+  }
+}

package/src/foundry/client/data/collections/folder.d.mts

@@ -0,0 +1,27 @@
+import type Document from "../../../common/abstract/document.d.mts";
+
+declare global {
+  /**
+   * The singleton collection of Folder documents which exist within the active World.
+   * This Collection is accessible within the Game object as game.fog.
+   *
+   * @see {@link Folder} The Folder document
+   */
+  class Folders extends WorldCollection<typeof foundry.documents.BaseFolder, "Folders"> {
+    constructor(data?: Document.Stored<Folder.ConfiguredInstance>["_source"][]);
+
+    /**
+     * Track which Folders are currently expanded in the UI
+     */
+    protected _expanded: Partial<Record<string, boolean>>;
+
+    static documentName: "Folder";
+
+    render(force?: boolean, context?: ApplicationOptions): void;
+
+    /**
+     * Refresh the display of any active JournalSheet instances where the folder list will change.
+     */
+    protected _refreshJournalEntrySheets(): void;
+  }
+}

package/src/foundry/client/data/collections/index.d.mts

@@ -0,0 +1,17 @@
+import "./actors.d.mts";
+import "./cards.d.mts";
+import "./combats.d.mts";
+import "./compendium-collection.d.mts";
+import "./compendium-folders.d.mts";
+import "./compendium-packs.d.mts";
+import "./fog.d.mts";
+import "./folder.d.mts";
+import "./items.d.mts";
+import "./journal.d.mts";
+import "./macros.d.mts";
+import "./messages.d.mts";
+import "./playlists.d.mts";
+import "./scenes.d.mts";
+import "./settings.d.mts";
+import "./tables.d.mts";
+import "./users.d.mts";

package/src/foundry/client/data/collections/items.d.mts

@@ -0,0 +1,14 @@
+export {};
+
+declare global {
+  /**
+   * The singleton collection of Item documents which exist within the active World.
+   * This Collection is accessible within the Game object as game.items.
+   *
+   * @see {@link Item} The Item document
+   * @see {@link ItemDirectory} The ItemDirectory sidebar directory
+   */
+  class Items extends WorldCollection<typeof foundry.documents.BaseItem, "Items"> {
+    static documentName: "Item";
+  }
+}

package/src/foundry/client/data/collections/journal.d.mts

@@ -0,0 +1,62 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * The singleton collection of JournalEntry documents which exist within the active World.
+   * This Collection is accessible within the Game object as game.journal.
+   *
+   * @see {@link JournalEntry} The JournalEntry document
+   * @see {@link JournalDirectory} The JournalDirectory sidebar directory
+   */
+  class Journal extends WorldCollection<typeof foundry.documents.BaseJournalEntry, "Journal"> {
+    static documentName: "JournalEntry";
+
+    /**
+     * Display a dialog which prompts the user to show a JournalEntry or JournalEntryPage to other players.
+     * @param doc - The JournalEntry or JournalEntryPage to show.
+     */
+    static showDialog<T extends JournalEntry | JournalEntryPage>(doc: T): Promise<T | void>;
+
+    /**
+     * Show the JournalEntry or JournalEntryPage to connected players.
+     * By default, the document will only be shown to players who have permission to observe it.
+     * If the force parameter is passed, the document will be shown to all players regardless of normal permission.
+     * @param doc     - The JournalEntry or JournalEntryPage to show.
+     * @param options - Additional options to configure behaviour.
+     */
+    static show<T extends JournalEntry | JournalEntryPage>(
+      doc: T,
+      options?: InexactPartial<{
+        /**
+         * Display the entry to all players regardless of normal permissions.
+         */
+        force: boolean;
+        /**
+         * An optional list of user IDs to show the document to. Otherwise it will be shown to all connected clients.
+         */
+        users: string[];
+      }>,
+    ): Promise<T>;
+
+    /**
+     * Share an image with connected players.
+     * @param src    - The image URL to share.
+     * @param config - Image sharing configuration.
+     */
+    static showImage(src: string, config?: InexactPartial<ImagePopout.ShareImageConfig>): void;
+
+    /**
+     * Open Socket listeners which transact JournalEntry data
+     * @remarks This is not marked as protected because it is used in {@link Game#activateSocketListeners}
+     */
+    protected static _activateSocketListeners(socket: io.Socket): void;
+
+    /**
+     * Handle a received request to show a JournalEntry or JournalEntryPage to the current client
+     * @param uuid - The UUID of the document to display for other players
+     * @param force   - Display the document regardless of normal permissions
+     *                  (default: `true`)
+     */
+    protected static _showEntry(uuid: string, force?: boolean): Promise<void>;
+  }
+}