@league-of-foundry-developers/foundry-vtt-types 12.331.3-beta → 12.331.5

package/src/foundry/client/data/abstract/client-document.d.mts

@@ -1,32 +1,50 @@
-import type { ConstructorOf, DeepPartial, InexactPartial, Mixin, ValueOf } from "../../../../types/utils.d.mts";
-import type { DatabaseCreateOperation } from "../../../common/abstract/_types.d.mts";
+import type {
+  Mixin,
+  FixedInstanceType,
+  Coalesce,
+  AnyObject,
+  NullishProps,
+  MaybePromise,
+  InexactPartial,
+  NullishCoalesce,
+} from "#utils";
 import type Document from "../../../common/abstract/document.d.mts";
 
-declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any = Document.Any> {
-  /** @privateRemarks All mixin classses should accept anything for its constructor. */
+import ApplicationV2 = foundry.applications.api.ApplicationV2;
+
+declare class InternalClientDocument<BaseDocument extends Document.Internal.Instance.Any = Document.Any> {
+  /** @privateRemarks All mixin classes should accept anything for its constructor. */
   constructor(...args: any[]);
 
   /**
    * A collection of Application instances which should be re-rendered whenever this document is updated.
    * The keys of this object are the application ids and the values are Application instances. Each
-   * Application in this object will have its render method called by {@link Document#render}.
-   * @see {@link Document#render}
+   * Application in this object will have its render method called by {@link Document.render | `Document#render`}.
+   * @see {@link Document.render | `Document#render`}
    * @defaultValue `{}`
+   * @remarks Created during construction via `defineProperty`, with options `{value: {}, writable: false, enumerable: false}`
    */
-  readonly apps: Record<string, Application | foundry.applications.api.ApplicationV2>;
+  readonly apps: Record<string, Application.Any | ApplicationV2.Any>;
 
   /**
    * A cached reference to the FormApplication instance used to configure this Document.
    * @defaultValue `null`
+   * @remarks Created during construction via `defineProperty`, with options `{value: null, writable: true, enumerable: false}`
+   *
+   * Foundry marked `@private`
    */
-  protected readonly _sheet: FormApplication | null; // TODO: Replace with InstanceType<ConfiguredSheetClass<T>> once the circular reference problem has been solved
+  protected _sheet: FixedInstanceType<
+    Document.ConfiguredSheetClassFor<Document.Internal.DocumentNameFor<BaseDocument>>
+  > | null;
 
   static name: "ClientDocumentMixin";
 
   /**
-   * @see abstract.Document#_initialize
+   * @see {@link abstract.Document._initialize | `abstract.Document#_initialize`}
+   * @remarks ClientDocument override calls `super`, then if `game._documentsReady`, calls {@link InternalClientDocument._safePrepareData | `this._safePrepareData`}
    */
-  protected _initialize(): void;
+  // options: not null (parameter default only)
+  protected _initialize(options?: Document.InitializeOptions): void;
 
   /**
    * Return a reference to the parent Collection instance which contains this Document.
@@ -36,8 +54,10 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
   /**
    * A reference to the Compendium Collection which contains this Document, if any, otherwise undefined.
    */
-  get compendium(): Document.MetadataFor<BaseDocument> extends CompendiumCollection.Metadata
-    ? CompendiumCollection<Document.MetadataFor<BaseDocument>>
+  get compendium(): Document.MetadataFor<
+    Document.Internal.DocumentNameFor<BaseDocument>
+  > extends CompendiumCollection.Metadata
+    ? CompendiumCollection<Document.MetadataFor<Document.Internal.DocumentNameFor<BaseDocument>>>
     : undefined;
 
   /**
@@ -72,12 +92,12 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    * actor.permission; // 2
    * ```
    */
-  get permission(): ValueOf<typeof CONST.DOCUMENT_OWNERSHIP_LEVELS>;
+  get permission(): CONST.DOCUMENT_OWNERSHIP_LEVELS | null;
 
   /**
    * Lazily obtain a FormApplication instance used to configure this Document, or null if no sheet is available.
    */
-  get sheet(): FormApplication | foundry.applications.api.ApplicationV2 | null;
+  get sheet(): FormApplication.Any | ApplicationV2.Any | null;
 
   /**
    * A boolean indicator for whether or not the current game User has at least limited visibility for this Document.
@@ -88,7 +108,7 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
   /**
    * Obtain the FormApplication class constructor which should be used to configure this Document.
    */
-  protected _getSheetClass(): ConstructorOf<FormApplication | foundry.applications.api.ApplicationV2> | null;
+  protected _getSheetClass(): FormApplication.AnyConstructor | ApplicationV2.AnyConstructor | null;
 
   /**
    * Safely prepare data for a Document, catching any errors.
@@ -121,16 +141,13 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
 
   /**
    * Render all Application instances which are connected to this document by calling their respective
-   * @see Application#render
+   * @see {@link Application.render | `Application#render`}
    * @param force   - Force rendering
    *                  (default: `false`)
    * @param context - Optional context
    *                  (default: `{}`)
    */
-  render(
-    force?: boolean,
-    context?: Application.RenderOptions | foundry.applications.api.ApplicationV2.RenderOptions,
-  ): void;
+  render(force?: boolean, context?: Application.RenderOptions | ApplicationV2.RenderOptions): void;
 
   /**
    * Determine the sort order for this Document by positioning it relative a target sibling.
@@ -138,44 +155,42 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    * @param options - Sorting options provided to SortingHelper.performIntegerSort
    * @returns The Document after it has been re-sorted
    */
-  sortRelative(options?: InexactPartial<ClientDocument.SortOptions<this>>): Promise<this>;
+  sortRelative(options?: ClientDocument.SortOptions<this>): Promise<this>;
 
   /**
    * Construct a UUID relative to another document.
    * @param doc - The document to compare against.
    */
-  getRelativeUuid(relative: ClientDocument): string;
+  getRelativeUUID(relative: ClientDocument): string;
 
   /**
-   * Createa  content link for this document
+   * Create a content link for this document
    * @param eventData - The parsed object of data provided by the drop transfer event.
    * @param options   - Additional options to configure link generation.
+   * @remarks Core's implementation doesn't use `eventData` here, but when it's passed in it's the return from
+   * {@link TextEditor.getDragEventData | `TextEditor.getDragEventData(someDragEvent)`}
    */
-  protected _createDocumentLink(
-    eventData: unknown,
-    options?: InexactPartial<{
-      /**
-       * A document to generate a link relative to.
-       */
-      relativeTo: ClientDocument;
-
-      /**
-       * A custom label to use instead of the document's name.
-       */
-      label: string;
-    }>,
-  ): string;
+  // options: not null (destructured)
+  _createDocumentLink(eventData?: AnyObject | null, options?: ClientDocument.CreateDocumentLinkOptions): string;
 
   /**
    * Handle clicking on a content link for this document.
    * @param event - The triggering click event.
+   * @remarks
+   * In `ClientDocument`, returns `this.sheet.render(true)`:
+   * - AppV1: returns that sheet
+   * - AppV2: returns a Promise of that sheet
+   *
+   * However it unfortunately has to be typed as `MaybePromise<unknown>` due to the {@link Macro._onClickDocumentLink | `Macro`} override,
+   * where `##executeScript` could return whatever a user-provided macro wants.
    */
-  _onClickDocumentLink(event: MouseEvent): unknown;
+  _onClickDocumentLink(event: MouseEvent): MaybePromise<unknown>;
 
-  /**
-   * @privateRemarks _onCreate, _onUpdate, and _onDelete are all overridden but with no signature changes.
-   * For type simplicity they are left off. These methods historically have been the source of a large amount of computation from tsc.
-   */
+  // _preCreate, _preUpdate, and _preDelete are all overridden with no signature changes,
+  // just to call `this.system._preX` if `super` doesn't return `false`
+
+  //  _onCreate, _onUpdate, and _onDelete are all overridden but with no signature changes.
+  // For type simplicity they are left off. These methods historically have been the source of a large amount of computation from tsc.
 
   /**
    * Orchestrate dispatching descendant document events to parent documents when embedded children are modified.
@@ -185,15 +200,16 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    * @param _parent    - The document with directly modified embedded documents.
    *                     Either this document or a descendant of this one.
    * @internal
+   * @remarks This has not been typed per-document as there does not appear to be a reason for users to ever extend or call this method.
+   * If you have a use case for this, please file an issue.
    */
   protected _dispatchDescendantDocumentEvents(
     event: ClientDocument.LifeCycleEventName,
     collection: string,
-    args: unknown[],
-    _parent: ClientDocument,
+    args: never,
+    _parent: never,
   ): void;
 
-  // TODO: Improve the data typing
   /**
    * Actions taken after descendant documents have been created, but before changes are applied to the client data.
    * @param parent     - The direct parent of the created Documents, may be this Document or a child
@@ -203,10 +219,10 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    * @param userId     - The ID of the User who triggered the operation
    */
   protected _preCreateDescendantDocuments(
-    parent: ClientDocument,
-    collection: string,
-    data: unknown[],
-    options: Document.PreCreateOptions<any>,
+    parent: never,
+    collection: never,
+    data: never,
+    options: never,
     userId: string,
   ): void;
 
@@ -220,13 +236,14 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    * @param userId     - The ID of the User who triggered the operation
    */
   protected _onCreateDescendantDocuments(
-    parent: ClientDocument,
-    collection: string,
-    documents: ClientDocument[],
-    data: unknown[],
-    options: Document.OnCreateOptions<any> & InexactPartial<{ render: boolean }>,
+    parent: never,
+    collection: never,
+    documents: never,
+    data: never,
+    options: never,
     userId: string,
   ): void;
+
   /**
    * Actions taken after descendant documents have been updated, but before changes are applied to the client data.
    * @param parent - The direct parent of the updated Documents, may be this Document or a child
@@ -236,10 +253,10 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    * @param userId - The ID of the User who triggered the operation
    */
   protected _preUpdateDescendantDocuments(
-    parent: ClientDocument,
-    collection: string,
-    changes: unknown[],
-    options: Document.PreUpdateOptions<any>,
+    parent: never,
+    collection: never,
+    changes: never,
+    options: never,
     userId: string,
   ): void;
 
@@ -253,11 +270,11 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    * @param userId - The ID of the User who triggered the operation
    */
   protected _onUpdateDescendantDocuments(
-    parent: ClientDocument,
-    collection: string,
-    documents: ClientDocument[],
-    changes: unknown[],
-    options: Document.OnUpdateOptions<any> & InexactPartial<{ render: boolean }>,
+    parent: never,
+    collection: never,
+    documents: never,
+    changes: never,
+    options: never,
     userId: string,
   ): void;
 
@@ -270,10 +287,10 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    * @param userId - The ID of the User who triggered the operation
    */
   protected _preDeleteDescendantDocuments(
-    parent: ClientDocument,
-    collection: string,
-    ids: string[],
-    options: Document.PreDeleteOptions<any>,
+    parent: never,
+    collection: never,
+    ids: never,
+    options: never,
     userId: string,
   ): void;
 
@@ -287,11 +304,11 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    * @param userId - The ID of the User who triggered the operation
    */
   protected _onDeleteDescendantDocuments(
-    parent: ClientDocument,
-    collection: string,
-    documents: ClientDocument[],
-    ids: string,
-    options: Document.OnDeleteOptions<any> & InexactPartial<{ render: boolean }>,
+    parent: never,
+    collection: never,
+    documents: never,
+    ids: string[],
+    options: never,
     userId: string,
   ): void;
 
@@ -299,52 +316,28 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    * Whenever the Document's sheet changes, close any existing applications for this Document, and re-render the new
    * sheet if one was already open.
    */
-  protected _onSheetChange(
-    options?: InexactPartial<{
-      /**
-       * Whether the sheet was originally open and needs to be re-opened.
-       */
-      sheetOpen: boolean;
-    }>,
-  ): Promise<void>;
+  // options: not null (destructured)
+  protected _onSheetChange(options?: ClientDocument.OnSheetChangeOptions): Promise<void>;
 
   /**
    * Gets the default new name for a Document
    * @param context - The context for which to create the Document name.
    */
-  static defaultName(
-    context?: InexactPartial<{
-      /** The sub-type of the document */
-      // TODO: See if the valid strings can be inferred from this type
-      type: string;
-      /** A parent document within which the created Document should belong */
-      parent: foundry.abstract.Document.Any;
-      /** A compendium pack within which the Document should be created */
-      pack: string;
-    }>,
-  ): string;
+  // context: not null (destructured)
+  static defaultName(context?: Document.DefaultNameContext<never, never>): string;
 
   /**
    * Present a Dialog form to create a new Document of this type.
    * Choose a name and a type from a select menu of types.
-   * @param data    - Initial data with which to populate the creation form
-   *                  (default: `{}`)
-   * @param context - Additional context options or dialog positioning options
-   *                  (default: `{}`)
-   * @returns A Promise which resolves to the created Document, or null if the dialog was
-   *          closed.
-   */
-  static createDialog<T extends Document.AnyConstructor>(
-    this: T,
-    data?: DeepPartial<Document.ConstructorDataFor<NoInfer<T>> & Record<string, unknown>>,
-    context?: Pick<DatabaseCreateOperation<InstanceType<NoInfer<T>>>, "parent" | "pack"> &
-      InexactPartial<
-        DialogOptions & {
-          /** A restriction the selectable sub-types of the Dialog. */
-          types: string[];
-        }
-      >,
-  ): Promise<Document.ToConfiguredInstance<T> | null | undefined>;
+   * @param data    - Initial data with which to populate the creation form    (default: `{}`)
+   * @param context - Additional context options or dialog positioning options (default: `{}`)
+   * @returns A Promise which resolves to the created Document, or null if the dialog was closed.
+   * @throws If the document has
+   * @privateRemarks `| undefined` is included in the return types of the specific document overrides due to {@link Document.create | `Document.create`}
+   * possibly being `undefined` if creation is cancelled by preCreate methods or hooks
+   */
+  // data: not null (parameter default only), option: not null (destructured)
+  static createDialog(data: never, context: never): Promise<unknown>;
 
   /**
    * Present a Dialog form to confirm deletion of this Document.
@@ -352,18 +345,20 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    *                  (default: `{}`)
    * @returns A Promise which resolves to the deleted Document
    */
-  deleteDialog(options?: Partial<DialogOptions>): Promise<this | false | null | undefined>;
+  // options: not null (parameter default only)
+  deleteDialog(options?: InexactPartial<Dialog.Options>): Promise<this | false | null | undefined>;
 
   /**
    * Export document data to a JSON file which can be saved by the client and later imported into a different session.
-   * @param options - Additional options passed to the {@link ClientDocument#toCompendium} method
+   * @param options - Additional options passed to the {@link ClientDocument.toCompendium | `ClientDocument#toCompendium`} method
    */
-  exportToJSON(options?: InexactPartial<ClientDocument.CompendiumExportOptions>): void;
+  // options: not null (destructured where forwarded)
+  exportToJSON(options?: ClientDocument.ToCompendiumOptions): void;
 
   /**
    * Serialize salient information about this Document when dragging it.
    */
-  toDragData(): DropData<BaseDocument>;
+  toDragData(): Document.DropData<Document.Internal.Instance.Complete<BaseDocument>>;
 
   /**
    * A helper function to handle obtaining the relevant Document from dropped data provided via a DataTransfer event.
@@ -375,12 +370,11 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    * @param options - Additional options which affect drop data behavior
    * @returns The resolved Document
    * @throws If a Document could not be retrieved from the provided data.
+   * @remarks Core's implementation in `ClientDocument` does not use `options` at all, no call passes any `options`
+   * anywhere in Foundry, and the JSDoc types it as simply `object`, so it cannot be typed more exactly than this.
    */
-  static fromDropData<T extends Document.AnyConstructor>(
-    this: T,
-    data: DropData<InstanceType<NoInfer<T>>>,
-    options?: FromDropDataOptions,
-  ): Promise<Document.ToConfiguredInstance<T> | undefined>;
+  // options: not null (parameter default only)
+  static fromDropData(data: Document.DropData<never>, options?: AnyObject): Promise<unknown>;
 
   /**
    * Create the Document from the given source with migration applied to it.
@@ -388,7 +382,7 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    *
    * This function must be used to create a document from data that predates the current core version.
    * It must be given nonpartial data matching the schema it had in the core version it is coming from.
-   * It applies legacy migrations to the source data before calling {@link Document.fromSource}.
+   * It applies legacy migrations to the source data before calling {@link Document.fromSource | `Document.fromSource`}.
    * If this function is not used to import old data, necessary migrations may not applied to the data
    * resulting in an incorrectly imported document.
    *
@@ -396,14 +390,12 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    * doesn't contain a `_stats` field, the data is assumed to be pre-V10, when the `_stats` field didn't exist yet.
    * The `_stats` field must not be stripped from the data before it is exported!
    * @param source - The document data that is imported.
-   * @param context - The model construction context passed to {@link Document.fromSource}.
+   * @param context - The model construction context passed to {@link Document.fromSource | `Document.fromSource`}.
    *                  (default: `context.strict=true`) Strict validation is enabled by default.
    */
-  static fromImport<T extends Document.AnyConstructor>(
-    this: T,
-    source: Record<string, unknown>,
-    context?: Document.ConstructionContext<Document.Any | null> & DataValidationOptions,
-  ): Promise<InstanceType<T>>;
+  // context: allowed to be null because spreading a variable with the value `null` into an object is allowed
+  static fromImport(source: never, context?: never): Promise<unknown>;
+
   /**
    * Update this Document using a provided JSON string.
    * @param json - JSON data string
@@ -424,33 +416,17 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    *                  (default: `{}`)
    * @returns A data object of cleaned data suitable for compendium import
    */
-  toCompendium<
-    FlagsOpt extends boolean = false,
-    SourceOpt extends boolean = true,
-    SortOpt extends boolean = true,
-    FolderOpt extends boolean = false,
-    OwnershipOpt extends boolean = false,
-    StateOpt extends boolean = true,
-    IdOpt extends boolean = false,
-  >(
+  // options: not null (destructured)
+  toCompendium<Options extends ClientDocument.ToCompendiumOptions | undefined = undefined>(
     pack?: CompendiumCollection<CompendiumCollection.Metadata> | null,
-    options?: InexactPartial<
-      ClientDocument.CompendiumExportOptions<FlagsOpt, SourceOpt, SortOpt, FolderOpt, OwnershipOpt, StateOpt, IdOpt>
-    >,
-  ): Omit<
-    Document.Internal.Instance.Complete<BaseDocument>["_source"],
-    | (IdOpt extends false ? "_id" : never)
-    | ClientDocument.OmitProperty<SortOpt, "sort" | "navigation" | "navOrder"> // helping out Scene
-    | ClientDocument.OmitProperty<FolderOpt, "folder">
-    | ClientDocument.OmitProperty<FlagsOpt, "flags">
-    | ClientDocument.OmitProperty<OwnershipOpt, "ownership">
-    | ClientDocument.OmitProperty<StateOpt, "active" | "fogReset" | "playing"> // helping out Playlist, Scene
-  >;
+    options?: Options,
+  ): ClientDocument.ToCompendiumReturnType<BaseDocument, Options>;
 
   /**
    * Create a content link for this Document.
    * @param options - Additional options to configure how the link is constructed.
    */
+  // options: not null (parameter default only)
   toAnchor(options?: TextEditor.EnrichmentAnchorOptions): HTMLAnchorElement;
 
   /**
@@ -459,6 +435,7 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    * @param options - The original enrichment options for cases where the Document embed content also contains text that must be enriched.
    * @returns A representation of the Document as HTML content, or null if such a representation could not be generated.
    */
+  // options: not null (parameter default only)
   toEmbed(
     config: TextEditor.DocumentHTMLEmbedConfig,
     options?: TextEditor.EnrichmentOptions,
@@ -509,7 +486,7 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    */
   protected _preCreateEmbeddedDocuments(
     embeddedName: string,
-    result: Record<string, unknown>[],
+    result: AnyObject[],
     options: Document.ModificationOptions,
     userId: string,
   ): void;
@@ -525,8 +502,8 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    */
   protected _onCreateEmbeddedDocuments(
     embeddedName: string,
-    documents: Document.Any[],
-    result: Record<string, unknown>[],
+    documents: never,
+    result: AnyObject[],
     options: Document.ModificationOptions,
     userId: string,
   ): void;
@@ -541,7 +518,7 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    */
   protected _preUpdateEmbeddedDocuments(
     embeddedName: string,
-    result: Record<string, unknown>[],
+    result: AnyObject[],
     options: Document.ModificationOptions,
     userId: string,
   ): void;
@@ -557,8 +534,8 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    */
   protected _onUpdateEmbeddedDocuments(
     embeddedName: string,
-    documents: Document.Any[],
-    result: Record<string, unknown>[],
+    documents: never,
+    result: AnyObject[],
     options: Document.ModificationContext<Document.Any | null>,
     userId: string,
   ): void;
@@ -589,17 +566,28 @@ declare class ClientDocument<BaseDocument extends Document.Internal.Instance.Any
    */
   protected _onDeleteEmbeddedDocuments(
     embeddedName: string,
-    documents: Document.Any[],
+    documents: never,
     result: string[],
     options: Document.ModificationContext<Document.Any | null>,
     userId: string,
   ): void;
 }
 
-declare const _ClientDocument: ClientDocument;
+type _ClientDocumentType = InternalClientDocument & Document.AnyConstructor;
+declare const _ClientDocument: _ClientDocumentType;
+
+type ClientDocumentMixinBaseClass = Document.Internal.Constructor;
 
 declare global {
-  type ClientDocument = typeof _ClientDocument;
+  /**
+   * This class does not really exist at runtime. It's here for types only.
+   */
+  class ClientDocument extends _ClientDocument {
+    // This may have be removed at some point in the future if it causes issues but the idea is to
+    // prevent operations like `new ClientDocument()` or `extends ClientDocument` because this does
+    // is not a class that really exists at runtime.
+    private constructor(...args: any[]);
+  }
 
   /**
    * A mixin which extends each Document definition with specialized client-side behaviors.
@@ -612,106 +600,150 @@ declare global {
   // Note(LukeAbby): The seemingly redundant merging in of `typeof AnyDocument` makes it easier for tsc to recognize that anything extending `ClientDocumentMixin` is also a document.
   function ClientDocumentMixin<BaseClass extends Document.Internal.Constructor>(
     Base: BaseClass,
-  ): typeof AnyDocument & Mixin<typeof ClientDocument<InstanceType<BaseClass>>, BaseClass>;
+  ): Mixin<typeof InternalClientDocument<FixedInstanceType<BaseClass>>, BaseClass>;
 
+  // TODO: Namespaces typically match the Mixin, not the non-exported class, but we're exporting the class for type reasons,
+  // TODO: so this is an exception?
   namespace ClientDocument {
     interface SortOptions<T, SortKey extends string = "sort"> extends SortingHelpers.SortOptions<T, SortKey> {
       /**
        * Additional data changes which are applied to each sorted document
        * @defaultValue `{}`
        */
-      updateData?: any;
+      updateData?: AnyObject;
     }
 
     // TODO: This may be better defined elsewhere
     type LifeCycleEventName = "preCreate" | "onCreate" | "preUpdate" | "onUpdate" | "preDelete" | "onDelete";
 
-    type OmitProperty<T extends boolean, Property extends string> = T extends true ? Property : never;
-
-    interface CompendiumExportOptions<
-      FlagsOpt extends boolean = false,
-      SourceOpt extends boolean = true,
-      SortOpt extends boolean = true,
-      FolderOpt extends boolean = false,
-      OwnershipOpt extends boolean = false,
-      StateOpt extends boolean = true,
-      IdOpt extends boolean = false,
-    > {
+    // Note(LukeAbby): If the property could be omitted it is. This is the safest option because in indeterminate cases access would be unsafe.
+    // In the future the indeterminate case could turn the property optional but that isn't done today because that's annoying to do for little benefit.
+    /** @internal */
+    type _OmitProperty<
+      Omit extends boolean | null | undefined,
+      Default extends boolean,
+      ToOmit extends string,
+    > = Omit extends true | (Default extends true ? undefined : never) ? ToOmit : never;
+
+    /** @internal */
+    type _ToCompendiumOptions = NullishProps<{
       /**
        * Clear the flags object
        * @defaultValue `false`
        */
-      clearFlags: FlagsOpt;
+      clearFlags: boolean;
 
       /**
        * Clear any prior source information
        * @defaultValue `true`
+       * @remarks Deletes `_stats.compendiumSource` and `_stats.duplicateSource`, won't delete legacy source flags
        */
-      clearSource: SourceOpt;
+      clearSource: boolean;
 
       /**
        * Clear the currently assigned folder and sort order
        * @defaultValue `true`
        */
-      clearSort: SortOpt;
+      clearSort: boolean;
 
       /**
        * Clear the currently assigned folder
        * @defaultValue `false`
        */
-      clearFolder: FolderOpt;
+      clearFolder: boolean;
 
       /**
        * Clear document ownership
        * @defaultValue `true`
        */
-      clearOwnership: OwnershipOpt;
+      clearOwnership: boolean;
 
       /**
        * Clear fields which store document state
        * @defaultValue `true`
        */
-      clearState: StateOpt;
+      clearState: boolean;
 
       /**
        * Retain the current Document id
        * @defaultValue `false`
        */
-      keepId: IdOpt;
-    }
-  }
-}
-
-export type DropData<T extends Document.Internal.Instance.Any> = T extends { id: string | undefined }
-  ? InternalData<T> & DropData.UUID
-  : InternalData<T>;
+      keepId: boolean;
+    }>;
 
-declare namespace DropData {
-  type Any = DropData<any>;
-
-  interface Data<T extends Document.Any> {
-    type: T["documentName"];
-    data: T["_source"];
-  }
+    interface ToCompendiumOptions extends _ToCompendiumOptions {}
 
-  interface UUID {
-    uuid: string;
-  }
-}
+    /** @internal */
+    type _CreateDocumentLinkOptions = NullishProps<{
+      /**
+       * A document to generate a link relative to.
+       * @remarks Ignored if falsey
+       */
+      relativeTo: ClientDocument;
 
-// This is yet another `AnyDocument` type.
-// It exists specifically because the `Document.AnyConstructor` type is too safe to be merged in with a mixin.
-// The `arg0: never, ...args: never[]` trick trips up the base constructor check and so this one with an actual `...args: any[]` one is used instead.
-declare class AnyDocument extends Document<any, any, any> {
-  constructor(...args: any[]);
-}
+      /**
+       * A custom label to use instead of the document's name.
+       * @defaultValue `this.name`
+       */
+      label: string;
+    }>;
+
+    interface CreateDocumentLinkOptions extends _CreateDocumentLinkOptions {}
+
+    /** The return type of {@link ClientDocument._onClickDocumentLink | `ClientDocument#_onClickDocumentLink`} if not overridden */
+    type OnClickDocumentLinkReturn = FormApplication.Any | Promise<ApplicationV2.Any>;
+
+    type ToCompendiumReturnType<
+      BaseDocument extends Document.Internal.Instance.Any,
+      Options extends ToCompendiumOptions | undefined,
+      // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    > = _ToCompendiumReturnType<BaseDocument, Coalesce<Options, {}>>;
+
+    type _ToCompendiumReturnType<
+      BaseDocument extends Document.Internal.Instance.Any,
+      Options extends ToCompendiumOptions,
+    > = _ClearFog<
+      Options["clearState"],
+      _ClearStats<
+        Options["clearSource"],
+        Omit<
+          Document.Internal.Instance.Complete<BaseDocument>["_source"],
+          | ClientDocument._OmitProperty<Options["clearFlags"], false, "flags">
+          | ClientDocument._OmitProperty<Options["clearSort"], true, "sort" | "navigation" | "navOrder"> // helping out Scene
+          | ClientDocument._OmitProperty<Options["clearFolder"], true, "folder">
+          | ClientDocument._OmitProperty<Options["clearOwnership"], true, "ownership">
+          | ClientDocument._OmitProperty<Options["clearState"], true, "active" | "playing"> // helping out Playlist, Scene
+          | (Options["keepId"] extends true ? never : "_id")
+        >
+      >
+    >;
+
+    /** @internal */
+    type _ClearStats<ClearSource extends boolean | null | undefined, SourceData extends object> = [
+      NullishCoalesce<ClearSource, true>,
+    ] extends [true]
+      ? {
+          [K in keyof SourceData]: "_stats" extends K
+            ? Omit<SourceData[K], "compendiumSource" | "duplicateSource">
+            : never;
+        }
+      : SourceData;
+
+    /** @internal */
+    type _ClearFog<ClearState extends boolean | null | undefined, SourceData extends object> = [
+      NullishCoalesce<ClearState, true>,
+    ] extends [true]
+      ? {
+          [K in keyof SourceData]: "fog" extends K ? Omit<SourceData[K], "reset"> : never;
+        }
+      : SourceData;
 
-type InternalData<T extends Document.Internal.Instance.Any> = DropData.Data<Document.Internal.Instance.Complete<T>>;
+    /** @internal */
+    type _OnSheetChangeOptions = NullishProps<{
+      /** Whether the sheet was originally open and needs to be re-opened. */
+      sheetOpen: boolean;
+    }>;
 
-interface FromDropDataOptions {
-  /**
-   * Import the provided document data into the World, if it is not already a World-level Document reference
-   * @defaultValue `false`
-   */
-  importWorld?: boolean;
+    interface OnSheetChangeOptions extends _OnSheetChangeOptions {}
+  }
 }