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

package/src/foundry/common/documents/folder.d.mts

@@ -1,4 +1,4 @@
-import type { AnyObject } from "../../../utils/index.d.mts";
+import type { AnyMutableObject } from "#utils";
 import type DataModel from "../abstract/data.d.mts";
 import type Document from "../abstract/document.mts";
 import type { DataField, SchemaField } from "../data/fields.d.mts";
@@ -29,12 +29,28 @@ declare abstract class BaseFolder<out _SubType extends BaseFolder.SubType = Base
    */
   constructor(...args: Folder.ConstructorArgs);
 
+  /**
+   * @defaultValue
+   * ```js
+   * mergeObject(super.metadata, {
+   *   name: "Folder",
+   *   collection: "folders",
+   *   label: "DOCUMENT.Folder",
+   *   labelPlural: "DOCUMENT.Folders",
+   *   coreTypes: CONST.FOLDER_DOCUMENT_TYPES,
+   *   schemaVersion: "12.324"
+   * })
+   * ```
+   */
   static override metadata: BaseFolder.Metadata;
 
   static override defineSchema(): BaseFolder.Schema;
 
-  // NOTE(LukeAbby): The `validateJoint` method override was left off because it didn't change the signature and it also seemed to cause a loop.
-  // See: https://gist.github.com/LukeAbby/43ee5c2a39cd33f3fac693d1d4a5653f
+  /**
+   * @remarks
+   * @throws If `data.folder === data._id` (no putting folders inside themselves)
+   * */
+  static validateJoint(data: Folder.Source): void;
 
   /**
    * Allow folder sorting modes
@@ -42,6 +58,12 @@ declare abstract class BaseFolder<out _SubType extends BaseFolder.SubType = Base
    */
   static SORTING_MODES: ("a" | "m")[];
 
+  /**
+   * @remarks Never returns an index entry, only ever {@linkcode Folder.Implementation} or `null`, as the `folders` collection of a
+   * compendium is always loaded and available synchronously
+   */
+  static override get(documentId: string, options?: Folder.Database.GetOptions): Folder.Implementation | null;
+
   /*
    * After this point these are not really overridden methods.
    * They are here because Foundry's documents are complex and have lots of edge cases.
@@ -59,37 +81,37 @@ declare abstract class BaseFolder<out _SubType extends BaseFolder.SubType = Base
   // Same as Document for now
   protected static override _initializationOrder(): Generator<[string, DataField.Any]>;
 
-  readonly parentCollection: Folder.ParentCollectionName | null;
+  override readonly parentCollection: Folder.ParentCollectionName | null;
 
-  readonly pack: string | null;
+  override readonly pack: string | null;
 
   static override get implementation(): Folder.ImplementationClass;
 
-  static get baseDocument(): typeof BaseFolder;
+  static override get baseDocument(): typeof BaseFolder;
 
-  static get collectionName(): Folder.ParentCollectionName;
+  static override get collectionName(): Folder.ParentCollectionName;
 
-  static get documentName(): Folder.Name;
+  static override get documentName(): Folder.Name;
 
-  static get TYPES(): BaseFolder.SubType[];
+  static override get TYPES(): BaseFolder.SubType[];
 
-  static get hasTypeData(): undefined;
+  static override get hasTypeData(): undefined;
 
-  static get hierarchy(): Folder.Hierarchy;
+  static override get hierarchy(): Folder.Hierarchy;
 
   override parent: BaseFolder.Parent;
 
-  static createDocuments<Temporary extends boolean | undefined = false>(
+  static override createDocuments<Temporary extends boolean | undefined = false>(
     data: Array<Folder.Implementation | Folder.CreateData> | undefined,
     operation?: Document.Database.CreateOperation<Folder.Database.Create<Temporary>>,
   ): Promise<Array<Document.TemporaryIf<Folder.Implementation, Temporary>>>;
 
-  static updateDocuments(
+  static override updateDocuments(
     updates: Folder.UpdateData[] | undefined,
     operation?: Document.Database.UpdateDocumentsOperation<Folder.Database.Update>,
   ): Promise<Folder.Implementation[]>;
 
-  static deleteDocuments(
+  static override deleteDocuments(
     ids: readonly string[] | undefined,
     operation?: Document.Database.DeleteDocumentsOperation<Folder.Database.Delete>,
   ): Promise<Folder.Implementation[]>;
@@ -106,8 +128,6 @@ declare abstract class BaseFolder<out _SubType extends BaseFolder.SubType = Base
 
   override delete(operation?: Folder.Database.DeleteOperation): Promise<this | undefined>;
 
-  static override get(documentId: string, options?: Folder.Database.GetOptions): Folder.Implementation | null;
-
   static override getCollectionName(name: string): null;
 
   // Same as Document for now
@@ -129,108 +149,142 @@ declare abstract class BaseFolder<out _SubType extends BaseFolder.SubType = Base
     key: Key,
   ): Promise<this>;
 
-  protected _preCreate(
+  protected override _preCreate(
     data: Folder.CreateData,
     options: Folder.Database.PreCreateOptions,
     user: User.Implementation,
   ): Promise<boolean | void>;
 
-  protected _onCreate(data: Folder.CreateData, options: Folder.Database.OnCreateOperation, userId: string): void;
+  protected override _onCreate(
+    data: Folder.CreateData,
+    options: Folder.Database.OnCreateOperation,
+    userId: string,
+  ): void;
 
-  protected static _preCreateOperation(
+  protected static override _preCreateOperation(
     documents: Folder.Implementation[],
     operation: Document.Database.PreCreateOperationStatic<Folder.Database.Create>,
     user: User.Implementation,
   ): Promise<boolean | void>;
 
-  protected static _onCreateOperation(
+  protected static override _onCreateOperation(
     documents: Folder.Implementation[],
     operation: Folder.Database.Create,
     user: User.Implementation,
   ): Promise<void>;
 
-  protected _preUpdate(
+  protected override _preUpdate(
     changed: Folder.UpdateData,
     options: Folder.Database.PreUpdateOptions,
     user: User.Implementation,
   ): Promise<boolean | void>;
 
-  protected _onUpdate(changed: Folder.UpdateData, options: Folder.Database.OnUpdateOperation, userId: string): void;
+  protected override _onUpdate(
+    changed: Folder.UpdateData,
+    options: Folder.Database.OnUpdateOperation,
+    userId: string,
+  ): void;
 
-  protected static _preUpdateOperation(
+  protected static override _preUpdateOperation(
     documents: Folder.Implementation[],
     operation: Folder.Database.Update,
     user: User.Implementation,
   ): Promise<boolean | void>;
 
-  protected static _onUpdateOperation(
+  protected static override _onUpdateOperation(
     documents: Folder.Implementation[],
     operation: Folder.Database.Update,
     user: User.Implementation,
   ): Promise<void>;
 
-  protected _preDelete(options: Folder.Database.PreDeleteOptions, user: User.Implementation): Promise<boolean | void>;
+  protected override _preDelete(
+    options: Folder.Database.PreDeleteOptions,
+    user: User.Implementation,
+  ): Promise<boolean | void>;
 
-  protected _onDelete(options: Folder.Database.OnDeleteOperation, userId: string): void;
+  protected override _onDelete(options: Folder.Database.OnDeleteOperation, userId: string): void;
 
-  protected static _preDeleteOperation(
+  protected static override _preDeleteOperation(
     documents: Folder.Implementation[],
     operation: Folder.Database.Delete,
     user: User.Implementation,
   ): Promise<boolean | void>;
 
-  protected static _onDeleteOperation(
+  protected static override _onDeleteOperation(
     documents: Folder.Implementation[],
     operation: Folder.Database.Delete,
     user: User.Implementation,
   ): Promise<void>;
 
-  static get hasSystemData(): undefined;
+  static override get hasSystemData(): undefined;
 
   // These data field things have been ticketed but will probably go into backlog hell for a while.
   // We'll end up copy and pasting without modification for now I think. It makes it a tiny bit easier to update though.
-  protected static _addDataFieldShims(data: AnyObject, shims: AnyObject, options?: Document.DataFieldShimOptions): void;
 
-  protected static _addDataFieldMigration(
-    data: AnyObject,
+  // options: not null (parameter default only in _addDataFieldShim)
+  protected static override _addDataFieldShims(
+    data: AnyMutableObject,
+    shims: Record<string, string>,
+    options?: Document.DataFieldShimOptions,
+  ): void;
+
+  // options: not null (parameter default only)
+  protected static override _addDataFieldShim(
+    data: AnyMutableObject,
+    oldKey: string,
+    newKey: string,
+    options?: Document.DataFieldShimOptions,
+  ): void;
+
+  protected static override _addDataFieldMigration(
+    data: AnyMutableObject,
     oldKey: string,
     newKey: string,
-    apply?: (data: AnyObject) => unknown,
-  ): unknown;
+    apply?: ((data: AnyMutableObject) => unknown) | null,
+  ): boolean;
 
-  protected static _logDataFieldMigration(
+  // options: not null (destructured where forwarded)
+  protected static override _logDataFieldMigration(
     oldKey: string,
     newKey: string,
     options?: LogCompatibilityWarningOptions,
   ): void;
 
-  protected static _onCreateDocuments(
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "The `Document._onCreateDocuments` static method is deprecated in favor of {@link Document._onCreateOperation | `Document._onCreateOperation`}"
+   */
+  protected static override _onCreateDocuments(
     documents: Folder.Implementation[],
     context: Document.ModificationContext<Folder.Parent>,
   ): Promise<void>;
 
-  protected static _onUpdateDocuments(
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "The `Document._onUpdateDocuments` static method is deprecated in favor of {@link Document._onUpdateOperation | `Document._onUpdateOperation`}"
+   */
+  protected static override _onUpdateDocuments(
     documents: Folder.Implementation[],
     context: Document.ModificationContext<Folder.Parent>,
   ): Promise<void>;
 
-  protected static _onDeleteDocuments(
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "The `Document._onDeleteDocuments` static method is deprecated in favor of {@link Document._onDeleteOperation | `Document._onDeleteOperation`}"
+   */
+  protected static override _onDeleteDocuments(
     documents: Folder.Implementation[],
     context: Document.ModificationContext<Folder.Parent>,
   ): Promise<void>;
 
   /* DataModel overrides */
 
-  protected static _schema: SchemaField<Folder.Schema>;
-
-  static get schema(): SchemaField<Folder.Schema>;
+  protected static override _schema: SchemaField<Folder.Schema>;
 
-  static validateJoint(data: Folder.Source): void;
+  static override get schema(): SchemaField<Folder.Schema>;
 
-  static override fromSource(
-    source: Folder.CreateData,
-    { strict, ...context }?: DataModel.FromSourceOptions,
-  ): Folder.Implementation;
+  // options: not null (parameter default only, destructured in super)
+  static override fromSource(source: Folder.CreateData, context?: DataModel.FromSourceOptions): Folder.Implementation;
 
   static override fromJSON(json: string): Folder.Implementation;
 }

package/src/foundry/common/documents/item.d.mts

@@ -1,4 +1,4 @@
-import type { AnyObject, AnyMutableObject } from "fvtt-types/utils";
+import type { AnyMutableObject } from "#utils";
 import type DataModel from "../abstract/data.d.mts";
 import type Document from "../abstract/document.mts";
 import type { DataField, SchemaField } from "../data/fields.d.mts";
@@ -29,6 +29,23 @@ declare abstract class BaseItem<out SubType extends Item.SubType = Item.SubType>
    */
   constructor(...args: Item.ConstructorArgs);
 
+  /**
+   * @defaultValue
+   * ```js
+   * mergeObject(super.metadata, {
+   *   name: "Item",
+   *   collection: "items",
+   *   hasTypeData: true,
+   *   indexed: true,
+   *   compendiumIndexFields: ["_id", "name", "img", "type", "sort", "folder"],
+   *   embedded: {ActiveEffect: "effects"},
+   *   label: "DOCUMENT.Item",
+   *   labelPlural: "DOCUMENT.Items",
+   *   permissions: {create: "ITEM_CREATE"},
+   *   schemaVersion: "12.324"
+   * })
+   * ```
+   */
   static override metadata: BaseItem.Metadata;
 
   static override defineSchema(): BaseItem.Schema;
@@ -43,17 +60,38 @@ declare abstract class BaseItem<out SubType extends Item.SubType = Item.SubType>
    * Determine default artwork based on the provided item data.
    * @param itemData - The source item data
    * @returns Candidate item image
+   * @remarks Core's implementation does not use `itemData`
    */
-  static getDefaultArtwork(itemData: BaseItem.CreateData): { img: string };
+  static getDefaultArtwork(itemData?: BaseItem.CreateData): Item.GetDefaultArtworkReturn;
 
-  override canUserModify(user: User.Implementation, action: "create" | "delete" | "update", data?: AnyObject): boolean;
+  /**
+   * @remarks If `this.isEmbedded`, uses `this.parent.canUserModify(user, "update")`, dropping `data` and forcing `action`,
+   * otherwise `super`'s (with all arguments forwarded). Core's `Actor` implementation doesn't override this method, so
+   * without further extension those are both {@link Document.canUserModify | `Document#canUserModify`}
+   */
+  // data: not null (parameter default only)
+  override canUserModify<Action extends "create" | "update" | "delete">(
+    user: User.Implementation,
+    action: Action,
+    data?: Document.CanUserModifyData<Item.Schema, Action>,
+  ): boolean;
 
+  /**
+   * @remarks If `this.isEmbedded`, uses `this.parent.testUserPermission`, otherwise `super`'s. Core's `Actor` implementation
+   * doesn't override this method, so without further extension those are both {@link Document.testUserPermission | `Document#testUserPermission`}
+   */
+  // options: not null (destructured)
   override testUserPermission(
     user: User.Implementation,
-    permission: keyof typeof CONST.DOCUMENT_OWNERSHIP_LEVELS | foundry.CONST.DOCUMENT_OWNERSHIP_LEVELS,
+    permission: Document.ActionPermission,
     options?: Document.TestUserPermissionOptions,
   ): boolean;
 
+  /**
+   * @remarks
+   * Migrations:
+   * - `flags.core.sourceId` to `_stats.compendiumSource` (since v12, no specified end)
+   */
   static override migrateData(source: AnyMutableObject): AnyMutableObject;
 
   /*
@@ -73,39 +111,39 @@ declare abstract class BaseItem<out SubType extends Item.SubType = Item.SubType>
   // Same as Document for now
   protected static override _initializationOrder(): Generator<[string, DataField.Any]>;
 
-  readonly parentCollection: Item.ParentCollectionName | null;
+  override readonly parentCollection: Item.ParentCollectionName | null;
 
-  readonly pack: string | null;
+  override readonly pack: string | null;
 
-  static get implementation(): Item.ImplementationClass;
+  static override get implementation(): Item.ImplementationClass;
 
-  static get baseDocument(): typeof BaseItem;
+  static override get baseDocument(): typeof BaseItem;
 
-  static get collectionName(): Item.ParentCollectionName;
+  static override get collectionName(): Item.ParentCollectionName;
 
-  static get documentName(): Item.Name;
+  static override get documentName(): Item.Name;
 
-  static get TYPES(): BaseItem.SubType[];
+  static override get TYPES(): BaseItem.SubType[];
 
-  static get hasTypeData(): true;
+  static override get hasTypeData(): true;
 
-  static get hierarchy(): Item.Hierarchy;
+  static override get hierarchy(): Item.Hierarchy;
 
   override system: Item.SystemOfType<SubType>;
 
   override parent: BaseItem.Parent;
 
-  static createDocuments<Temporary extends boolean | undefined = false>(
+  static override createDocuments<Temporary extends boolean | undefined = false>(
     data: Array<Item.Implementation | Item.CreateData> | undefined,
     operation?: Document.Database.CreateOperation<Item.Database.Create<Temporary>>,
   ): Promise<Array<Document.TemporaryIf<Item.Implementation, Temporary>>>;
 
-  static updateDocuments(
+  static override updateDocuments(
     updates: Item.UpdateData[] | undefined,
     operation?: Document.Database.UpdateDocumentsOperation<Item.Database.Update>,
   ): Promise<Item.Implementation[]>;
 
-  static deleteDocuments(
+  static override deleteDocuments(
     ids: readonly string[] | undefined,
     operation?: Document.Database.DeleteDocumentsOperation<Item.Database.Delete>,
   ): Promise<Item.Implementation[]>;
@@ -178,108 +216,140 @@ declare abstract class BaseItem<out SubType extends Item.SubType = Item.SubType>
     key: Key,
   ): Promise<this>;
 
-  protected _preCreate(
+  protected override _preCreate(
     data: Item.CreateData,
     options: Item.Database.PreCreateOptions,
     user: User.Implementation,
   ): Promise<boolean | void>;
 
-  protected _onCreate(data: Item.CreateData, options: Item.Database.OnCreateOperation, userId: string): void;
+  protected override _onCreate(data: Item.CreateData, options: Item.Database.OnCreateOperation, userId: string): void;
 
-  protected static _preCreateOperation(
+  protected static override _preCreateOperation(
     documents: Item.Implementation[],
     operation: Document.Database.PreCreateOperationStatic<Item.Database.Create>,
     user: User.Implementation,
   ): Promise<boolean | void>;
 
-  protected static _onCreateOperation(
+  protected static override _onCreateOperation(
     documents: Item.Implementation[],
     operation: Item.Database.Create,
     user: User.Implementation,
   ): Promise<void>;
 
-  protected _preUpdate(
+  protected override _preUpdate(
     changed: Item.UpdateData,
     options: Item.Database.PreUpdateOptions,
     user: User.Implementation,
   ): Promise<boolean | void>;
 
-  protected _onUpdate(changed: Item.UpdateData, options: Item.Database.OnUpdateOperation, userId: string): void;
+  protected override _onUpdate(
+    changed: Item.UpdateData,
+    options: Item.Database.OnUpdateOperation,
+    userId: string,
+  ): void;
 
-  protected static _preUpdateOperation(
+  protected static override _preUpdateOperation(
     documents: Item.Implementation[],
     operation: Item.Database.Update,
     user: User.Implementation,
   ): Promise<boolean | void>;
 
-  protected static _onUpdateOperation(
+  protected static override _onUpdateOperation(
     documents: Item.Implementation[],
     operation: Item.Database.Update,
     user: User.Implementation,
   ): Promise<void>;
 
-  protected _preDelete(options: Item.Database.PreDeleteOptions, user: User.Implementation): Promise<boolean | void>;
+  protected override _preDelete(
+    options: Item.Database.PreDeleteOptions,
+    user: User.Implementation,
+  ): Promise<boolean | void>;
 
-  protected _onDelete(options: Item.Database.OnDeleteOperation, userId: string): void;
+  protected override _onDelete(options: Item.Database.OnDeleteOperation, userId: string): void;
 
-  protected static _preDeleteOperation(
+  protected static override _preDeleteOperation(
     documents: Item.Implementation[],
     operation: Item.Database.Delete,
     user: User.Implementation,
   ): Promise<boolean | void>;
 
-  protected static _onDeleteOperation(
+  protected static override _onDeleteOperation(
     documents: Item.Implementation[],
     operation: Item.Database.Delete,
     user: User.Implementation,
   ): Promise<void>;
 
-  static get hasSystemData(): true;
+  static override get hasSystemData(): true;
 
   // These data field things have been ticketed but will probably go into backlog hell for a while.
   // We'll end up copy and pasting without modification for now I think. It makes it a tiny bit easier to update though.
-  protected static _addDataFieldShims(data: AnyObject, shims: AnyObject, options?: Document.DataFieldShimOptions): void;
 
-  protected static _addDataFieldMigration(
-    data: AnyObject,
+  // options: not null (parameter default only in _addDataFieldShim)
+  protected static override _addDataFieldShims(
+    data: AnyMutableObject,
+    shims: Record<string, string>,
+    options?: Document.DataFieldShimOptions,
+  ): void;
+
+  // options: not null (parameter default only)
+  protected static override _addDataFieldShim(
+    data: AnyMutableObject,
     oldKey: string,
     newKey: string,
-    apply?: (data: AnyObject) => unknown,
-  ): unknown;
+    options?: Document.DataFieldShimOptions,
+  ): void;
+
+  protected static override _addDataFieldMigration(
+    data: AnyMutableObject,
+    oldKey: string,
+    newKey: string,
+    apply?: ((data: AnyMutableObject) => unknown) | null,
+  ): boolean;
 
-  protected static _logDataFieldMigration(
+  // options: not null (destructured where forwarded)
+  protected static override _logDataFieldMigration(
     oldKey: string,
     newKey: string,
     options?: LogCompatibilityWarningOptions,
   ): void;
 
-  protected static _onCreateDocuments(
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "The `Document._onCreateDocuments` static method is deprecated in favor of {@link Document._onCreateOperation | `Document._onCreateOperation`}"
+   */
+  protected static override _onCreateDocuments(
     documents: Item.Implementation[],
     context: Document.ModificationContext<Item.Parent>,
   ): Promise<void>;
 
-  protected static _onUpdateDocuments(
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "The `Document._onUpdateDocuments` static method is deprecated in favor of {@link Document._onUpdateOperation | `Document._onUpdateOperation`}"
+   */
+  protected static override _onUpdateDocuments(
     documents: Item.Implementation[],
     context: Document.ModificationContext<Item.Parent>,
   ): Promise<void>;
 
-  protected static _onDeleteDocuments(
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "The `Document._onDeleteDocuments` static method is deprecated in favor of {@link Document._onDeleteOperation | `Document._onDeleteOperation`}"
+   */
+  protected static override _onDeleteDocuments(
     documents: Item.Implementation[],
     context: Document.ModificationContext<Item.Parent>,
   ): Promise<void>;
 
   /* DataModel overrides */
 
-  protected static _schema: SchemaField<Item.Schema>;
+  protected static override _schema: SchemaField<Item.Schema>;
 
-  static get schema(): SchemaField<Item.Schema>;
+  static override get schema(): SchemaField<Item.Schema>;
 
-  static validateJoint(data: Item.Source): void;
+  static override validateJoint(data: Item.Source): void;
 
-  static override fromSource(
-    source: Item.CreateData,
-    { strict, ...context }?: DataModel.FromSourceOptions,
-  ): Item.Implementation;
+  // options: not null (parameter default only, destructured in super)
+  static override fromSource(source: Item.CreateData, context?: DataModel.FromSourceOptions): Item.Implementation;
 
   static override fromJSON(json: string): Item.Implementation;
 }
@@ -314,6 +384,7 @@ declare namespace BaseItem {
   export import Schema = Item.Schema;
   export import DatabaseOperation = Item.Database;
   export import Flags = Item.Flags;
+  export import GetDefaultArtworkReturn = Item.GetDefaultArtworkReturn;
 
   // The document subclasses override `system` anyways.
   // There's no point in doing expensive computation work comparing the base class system.