@league-of-foundry-developers/foundry-vtt-types 9.280.1 → 12.331.2-beta

package/src/foundry/common/data/module.d.mts

@@ -0,0 +1,9 @@
+// In Foundry itself this file contains re-exports of these other modules.
+// Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
+// While `.mts` could work, to avoid `import/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import/extensions */
+
+export * as validators from "./validators.mjs";
+export * as validation from "./validation-failure.mjs";
+export * as fields from "./fields.mjs";
+export * from "./data.mjs";

package/src/foundry/common/data/validation-failure.d.mts

@@ -0,0 +1,174 @@
+/**
+ * A class responsible for recording information about a validation failure.
+ */
+export class DataModelValidationFailure {
+  constructor(options: DataModelValidationFailure.ConstructorArgs);
+
+  /**
+   * The value that failed validation for this field.
+   */
+  invalidValue: unknown;
+
+  /**
+   * The value it was replaced by, if any.
+   */
+  fallback: unknown;
+
+  /**
+   * Whether the value was dropped from some parent collection.
+   * @defaultValue `false`
+   */
+  dropped: boolean;
+
+  /**
+   * The validation error message.
+   */
+  message: string | undefined;
+
+  /**
+   * If this field contains other fields that are validated as part of its validation, their results are recorded here.
+   * @defaultValue `{}`
+   */
+  fields: Record<string, DataModelValidationFailure>;
+
+  /**
+   * If this field contains a list of elements that are validated as part of its validation, their results are recorded here.
+   */
+  elements: DataModelValidationFailure.ElementValidationFailure[];
+
+  /**
+   * Record whether a validation failure is unresolved.
+   * This reports as true if validation for this field or any hierarchically contained field is unresolved.
+   * A failure is unresolved if the value was invalid and there was no valid fallback value available.
+   * @defaultValue `false`
+   */
+  unresolved: boolean;
+
+  /**
+   * Return this validation failure as an Error object.
+   */
+  asError(): DataModelValidationError;
+
+  /**
+   * Whether this failure contains other sub-failures.
+   */
+  isEmpty(): boolean;
+
+  /**
+   * Return the base properties of this failure, omitting any nested failures.
+   */
+  toObject(): DataModelValidationFailure.ToObject;
+
+  /**
+   * Represent the DataModelValidationFailure as a string.
+   */
+  toString(): string;
+}
+
+/**
+ * A specialised Error to indicate a model validation failure.
+ */
+export class DataModelValidationError extends Error {
+  /**
+   * @param failure - The failure that triggered this error or an error message
+   * @param params  - Additional Error constructor parameters
+   */
+  constructor(failure: DataModelValidationFailure | string, options?: { cause?: Error | string });
+
+  /**
+   * Retrieve the root failure that caused this error, or a specific sub-failure via a path.
+   * @param path - The property path to the failure.
+   *
+   * @example Retrieving a failure.
+   * ```js
+   * const changes = {
+   *   "foo.bar": "validValue",
+   *   "foo.baz": "invalidValue"
+   * };
+   * try {
+   *   doc.validate(expandObject(changes));
+   * } catch ( err ) {
+   *   const failure = err.getFailure("foo.baz");
+   *   console.log(failure.invalidValue); // "invalidValue"
+   * }
+   * ```
+   */
+  getFailure(path?: string): DataModelValidationFailure | void;
+
+  /**
+   * Retrieve a flattened object of all the properties that failed validation as part of this error.
+   *
+   * @example Removing invalid changes from an update delta.
+   * ```js
+   * const changes = {
+   *   "foo.bar": "validValue",
+   *   "foo.baz": "invalidValue"
+   * };
+   * try {
+   *   doc.validate(expandObject(changes));
+   * } catch ( err ) {
+   *   const failures = err.getAllFailures();
+   *   if ( failures ) {
+   *     for ( const prop in failures ) delete changes[prop];
+   *     doc.validate(expandObject(changes));
+   *   }
+   * }
+   * ```
+   */
+  getAllFailures(): Record<string, DataModelValidationFailure> | void;
+
+  /**
+   * Log the validation error as a table.
+   */
+  logAsTable(): void;
+
+  /**
+   * Generate a nested tree view of the error as an HTML string.
+   */
+  asHTML(): string;
+}
+
+declare namespace DataModelValidationFailure {
+  interface ConstructorArgs {
+    // The `| undefined` is redundant with `unknown` but it's provided anyways for easy auditing.
+
+    /** The value that failed validation for this field. */
+    invalidValue?: unknown | undefined;
+
+    /**  The value it was replaced by, if any. */
+    fallback?: unknown | undefined;
+
+    /**
+     * Whether the value was dropped from some parent collection.
+     * @defaultValue `false`
+     */
+    dropped?: boolean | undefined;
+
+    /** The validation error message. */
+    message?: string | undefined;
+
+    /**
+     * Whether this failure was unresolved
+     * @defaultValue `false`
+     */
+    unresolved?: boolean | undefined;
+  }
+
+  interface ElementValidationFailure {
+    /** Either the element's index or some other identifier for it. */
+    id: string | number;
+
+    /** Optionally a user-friendly name for the element. */
+    name?: string;
+
+    /** The element's validation failure. */
+    failure: DataModelValidationFailure;
+  }
+
+  interface ToObject {
+    invalidValue?: unknown | undefined;
+    fallback?: unknown | undefined;
+    dropped?: boolean | undefined;
+    message?: string | undefined;
+  }
+}

package/src/foundry/common/data/validators.d.mts

@@ -0,0 +1,30 @@
+/**
+ * Test whether a string is a valid 16 character UID
+ */
+export declare function isValidId(id: string | null): boolean;
+
+/**
+ * Test whether a file path has an extension in a list of provided extensions
+ */
+export declare function hasFileExtension(path: string | null, extensions: string[]): boolean;
+
+/**
+ * Test whether a string data blob contains base64 data, optionally of a specific type or types
+ * @param data  - The candidate string data
+ * @param types - An array of allowed mime types to test
+ */
+export declare function isBase64Data(data: string, types?: string[]): boolean;
+
+/**
+ * Test whether an input represents a valid 6-character color string
+ * @param color - The input string to test
+ * @returns Is the string a valid color?
+ */
+export declare function isColorString(color: string): boolean;
+
+/**
+ * Assert that the given value parses as a valid JSON string
+ * @param val - The value to test
+ * @returns Is the String valid JSON?
+ */
+export declare function isJSON(val: string): boolean;

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

@@ -0,0 +1,35 @@
+// In Foundry itself this file contains re-exports of these other modules.
+// Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
+// While `.mts` could work, to avoid `import/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import/extensions */
+
+export { default as BaseActiveEffect } from "./active-effect.mjs";
+export { default as BaseActorDelta } from "./actor-delta.mjs";
+export { default as BaseActor } from "./actor.mjs";
+export { default as BaseAdventure } from "./adventure.mjs";
+export { default as BaseAmbientLight } from "./ambient-light.mjs";
+export { default as BaseAmbientSound } from "./ambient-sound.mjs";
+export { default as BaseCard } from "./card.mjs";
+export { default as BaseCards } from "./cards.mjs";
+export { default as BaseChatMessage } from "./chat-message.mjs";
+export { default as BaseCombat } from "./combat.mjs";
+export { default as BaseCombatant } from "./combatant.mjs";
+export { default as BaseDrawing } from "./drawing.mjs";
+export { default as BaseFogExploration } from "./fog-exploration.mjs";
+export { default as BaseFolder } from "./folder.mjs";
+export { default as BaseItem } from "./item.mjs";
+export { default as BaseJournalEntry } from "./journal-entry.mjs";
+export { default as BaseJournalEntryPage } from "./journal-entry-page.mjs";
+export { default as BaseMacro } from "./macro.mjs";
+export { default as BaseMeasuredTemplate } from "./measured-template.mjs";
+export { default as BaseNote } from "./note.mjs";
+export { default as BasePlaylist } from "./playlist.mjs";
+export { default as BasePlaylistSound } from "./playlist-sound.mjs";
+export { default as BaseRollTable } from "./roll-table.mjs";
+export { default as BaseScene } from "./scene.mjs";
+export { default as BaseSetting } from "./setting.mjs";
+export { default as BaseTableResult } from "./table-result.mjs";
+export { default as BaseTile } from "./tile.mjs";
+export { default as BaseToken } from "./token.mjs";
+export { default as BaseUser } from "./user.mjs";
+export { default as BaseWall } from "./wall.mjs";

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

@@ -0,0 +1,175 @@
+import type BaseActiveEffect from "./active-effect.d.mts";
+import type BaseActorDelta from "./actor-delta.d.mts";
+import type BaseActor from "./actor.d.mts";
+import type BaseAdventure from "./adventure.d.mts";
+import type BaseAmbientLight from "./ambient-light.d.mts";
+import type BaseAmbientSound from "./ambient-sound.d.mts";
+import type BaseCard from "./card.d.mts";
+import type BaseCards from "./cards.d.mts";
+import type BaseChatMessage from "./chat-message.d.mts";
+import type BaseCombat from "./combat.d.mts";
+import type BaseCombatant from "./combatant.d.mts";
+import type BaseDrawing from "./drawing.d.mts";
+import type BaseFogExploration from "./fog-exploration.d.mts";
+import type BaseFolder from "./folder.d.mts";
+import type BaseItem from "./item.d.mts";
+import type BaseJournalEntryPage from "./journal-entry-page.d.mts";
+import type BaseJournalEntry from "./journal-entry.d.mts";
+import type BaseMacro from "./macro.d.mts";
+import type BaseMeasuredTemplate from "./measured-template.d.mts";
+import type BaseNote from "./note.d.mts";
+import type BasePlaylistSound from "./playlist-sound.d.mts";
+import type BasePlaylist from "./playlist.d.mts";
+import type BaseRollTable from "./roll-table.d.mts";
+import type BaseScene from "./scene.d.mts";
+import type BaseSetting from "./setting.d.mts";
+import type BaseTableResult from "./table-result.d.mts";
+import type BaseTile from "./tile.d.mts";
+import type BaseToken from "./token.d.mts";
+import type BaseUser from "./user.d.mts";
+import type BaseWall from "./wall.d.mts";
+
+export type ActiveEffectData = BaseActiveEffect.Properties;
+
+export type EffectDurationData = BaseActiveEffect.Properties["duration"];
+
+// TODO(LukeAbby): This understandably adds a circular loop because `DataField` depends on `EffectChangeData`.
+// export type EffectChangeData = BaseActiveEffect.Properties["changes"][number];
+
+// TODO(LukeAbby): Audit. This is used both as an assignment, constructor, and initialized type. It's likely this isn't
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export type EffectChangeData = {
+  /**
+   * The attribute path in the Actor or Item data which the change modifies
+   * @defaultValue `""`
+   */
+  key: string;
+
+  /**
+   * The value of the change effect
+   * @defaultValue `""`
+   */
+  value: string;
+
+  /**
+   * The modification mode with which the change is applied
+   * @defaultValue `CONST.ACTIVE_EFFECT_MODES.ADD`
+   */
+  mode: number | null;
+
+  /**
+   * The priority level with which this change is applied
+   * @defaultValue `null`
+   */
+  priority: number | null;
+};
+
+export type ActorData = BaseActor.Properties;
+
+export type ActorDeltaData = BaseActorDelta.Properties;
+
+export type AdventureData = BaseAdventure.Properties;
+
+export type AmbientLightData = BaseAmbientLight.Properties;
+
+export type AmbientSoundData = BaseAmbientSound.Properties;
+
+export interface AmbientSoundEffect {
+  type: string;
+  intensity: number;
+} // TODO: Audit and maybe move when BaseAmbientSound's schema is updated.
+
+export type CardData = BaseCard.Properties;
+
+export type CardFaceData = BaseCard.Properties["faces"][number];
+
+export type CardsData = BaseCards.Properties;
+
+export type ChatMessageData = BaseChatMessage.Properties;
+
+export type ChatSpeakerData = BaseChatMessage.Properties["speaker"];
+
+export type CombatData = BaseCombat.Properties;
+
+export type CombatantData = BaseCombatant.Properties;
+
+export type DrawingData = BaseDrawing.Properties;
+
+export type FogExplorationData = BaseFogExploration.Properties;
+
+export type FolderData = BaseFolder.Properties;
+
+export type ItemData = BaseItem.Properties;
+
+export type JournalEntryData = BaseJournalEntry.Properties;
+
+export type JournalEntryPageImageData = BaseJournalEntryPage.Properties["image"];
+
+export type JournalEntryPageTextData = BaseJournalEntryPage.Properties["text"];
+
+export type JournalEntryPageVideoData = BaseJournalEntryPage.Properties["video"];
+
+export type JournalEntryPageTitleData = BaseJournalEntryPage.Properties["title"];
+
+export type JournalEntryPageData = BaseJournalEntryPage.Properties;
+
+export type MacroData = BaseMacro.Properties;
+
+export type MeasuredTemplateData = BaseMeasuredTemplate.Properties;
+
+export type NoteData = BaseNote.Properties;
+
+export type PlaylistData = BasePlaylist.Properties;
+
+export type PlaylistSoundData = BasePlaylistSound.Properties;
+
+export type RollTableData = BaseRollTable.Properties;
+
+export type SceneData = BaseScene.Properties;
+
+export type GridData = BaseScene.Properties["grid"];
+
+// TODO: Remove when BaseScene's schema is updated.
+// @ts-expect-error This still has to be typed
+export type EnvironmentData = BaseScene.Properties["environment"]["base"];
+
+export interface _GlobalLightData {
+  enabled: number; // TODO: Report as a likely error.
+  bright: boolean;
+}
+
+// TODO: Remove when BaseScene's schema is updated.
+// @ts-expect-error This still has to be typed
+export type GlobalLightData = BaseScene.Properties["environment"]["globalLight"];
+
+// TODO: Remove when BaseScene's schema is updated.
+// @ts-expect-error This still has to be typed
+export type SceneEnvironmentData = BaseScene.Properties["environment"];
+
+export type RegionData = unknown; // TODO: Add when BaseRegion's schema is added.
+
+export type RegionBehaviorData = unknown; // TODO: Add when BaseRegionBehavior's schema is added.
+
+export type SettingData = BaseSetting.Properties;
+
+export type TableResultData = BaseTableResult.Properties;
+
+export type TileOcclusionData = BaseTile.Properties["occlusion"];
+
+export type TileVideoData = BaseTile.Properties["video"];
+
+export type TileData = BaseTile.Properties;
+
+export type TokenData = BaseToken.Properties;
+
+export type TokenSightData = BaseToken.Properties["sight"];
+
+export type TokenDetectionMode = BaseToken.Properties["detectionModes"][number];
+
+export type TokenBarData = BaseToken.Properties["bar1"];
+
+export type UserData = BaseUser.Properties;
+
+export type WallData = BaseWall.Properties;
+
+export type WallThresholdData = BaseWall.Properties["threshold"];

package/src/foundry/common/documents/active-effect.d.mts

@@ -0,0 +1,238 @@
+import type { InterfaceToObject } from "../../../types/helperTypes.d.mts";
+import type { AnyObject, InexactPartial } from "../../../types/utils.mts";
+import type Document from "../abstract/document.mts";
+import type * as CONST from "../constants.mts";
+import type * as fields from "../data/fields.d.mts";
+import type * as documents from "./_module.mts";
+
+/**
+ * The ActiveEffect Document.
+ */
+// Note(LukeAbby): You may wonder why documents don't simply pass the `Parent` generic parameter.
+// This pattern evolved from trying to avoid circular loops and even internal tsc errors.
+// See: https://gist.github.com/LukeAbby/0d01b6e20ef19ebc304d7d18cef9cc21
+declare class BaseActiveEffect extends Document<"ActiveEffect", BaseActiveEffect.Schema, any> {
+  /**
+   * @param data    - Initial data from which to construct the ActiveEffect
+   * @param context - Construction context options
+   */
+  // TODO(LukeAbby): This constructor is causing a circular error.
+  // constructor(data?: BaseActiveEffect.ConstructorData, context?: Document.ConstructionContext<BaseActiveEffect.Parent>);
+
+  override parent: BaseActiveEffect.Parent;
+
+  override canUserModify(user: documents.BaseUser, action: "create" | "update" | "delete", data?: AnyObject): boolean;
+
+  static override metadata: BaseActiveEffect.Metadata;
+
+  static override defineSchema(): BaseActiveEffect.Schema;
+
+  override testUserPermission(
+    user: documents.BaseUser,
+    permission: keyof typeof CONST.DOCUMENT_OWNERSHIP_LEVELS | CONST.DOCUMENT_OWNERSHIP_LEVELS,
+    options?: InexactPartial<{
+      /**
+       * Require the exact permission level requested?
+       * @defaultValue `false`
+       */
+      exact: boolean;
+    }>,
+  ): boolean;
+
+  /**
+   * @privateRemarks _preCreate overridden but with no signature changes.
+   * For type simplicity it is left off. These methods historically have been the source of a large amount of computation from tsc.
+   */
+
+  static override migrateData(source: AnyObject): AnyObject;
+
+  /**
+   * @deprecated since v11, will be removed in v13
+   * @remarks Replaced by `name`
+   */
+  get label(): this["name"];
+
+  set label(value);
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks Replaced by `img`
+   */
+  get icon(): this["img"];
+
+  set icon(value);
+}
+
+export default BaseActiveEffect;
+
+declare namespace BaseActiveEffect {
+  type Parent = Actor.ConfiguredInstance | Item.ConfiguredInstance | null;
+
+  type TypeNames = Game.Model.TypeNames<"ActiveEffect">;
+
+  type Metadata = Document.MetadataFor<BaseActiveEffect>;
+
+  type SchemaField = fields.SchemaField<Schema>;
+  type ConstructorData = fields.SchemaField.InnerConstructorType<Schema>;
+  type UpdateData = fields.SchemaField.InnerAssignmentType<Schema>;
+  type Properties = fields.SchemaField.InnerInitializedType<Schema>;
+  type Source = fields.SchemaField.InnerPersistedType<Schema>;
+
+  interface Schema extends DataSchema {
+    /**
+     * The _id which uniquely identifies the ActiveEffect within a parent Actor or Item
+     * @defaultValue `null`
+     */
+    _id: fields.DocumentIdField;
+
+    /**
+     * The name of the ActiveEffect
+     * @defaultValue `""`
+     */
+    name: fields.StringField<{ required: true; label: "EFFECT.Label" }>;
+
+    /**
+     * An image path used to depict the ActiveEffect as an icon
+     * @defaultValue `null`
+     */
+    img: fields.FilePathField<{ categories: "IMAGE"[]; label: "EFFECT.Image" }>;
+
+    type: fields.DocumentTypeField<typeof BaseActiveEffect, { initial: typeof foundry.CONST.BASE_DOCUMENT_TYPE }>;
+
+    system: fields.TypeDataField<typeof BaseActiveEffect>;
+
+    /**
+     * The array of EffectChangeData objects which the ActiveEffect applies
+     * @defaultValue `[]`
+     */
+    changes: fields.ArrayField<
+      fields.SchemaField<{
+        /**
+         * The attribute path in the Actor or Item data which the change modifies
+         * @defaultValue `""`
+         */
+        key: fields.StringField<{ required: true; label: "EFFECT.ChangeKey" }>;
+
+        /**
+         * The value of the change effect
+         * @defaultValue `""`
+         */
+        value: fields.StringField<{ required: true; label: "EFFECT.ChangeValue" }>;
+
+        /**
+         * The modification mode with which the change is applied
+         * @defaultValue `CONST.ACTIVE_EFFECT_MODES.ADD`
+         */
+        mode: fields.NumberField<{
+          integer: true;
+          initial: typeof CONST.ACTIVE_EFFECT_MODES.ADD;
+          label: "EFFECT.ChangeMode";
+        }>;
+
+        /**
+         * The priority level with which this change is applied
+         * @defaultValue `null`
+         */
+        priority: fields.NumberField;
+      }>
+    >;
+
+    /**
+     * Is this ActiveEffect currently disabled?
+     * @defaultValue `false`
+     */
+    disabled: fields.BooleanField;
+
+    /**
+     * An EffectDurationData object which describes the duration of the ActiveEffect
+     * @defaultValue see properties
+     */
+    duration: fields.SchemaField<{
+      /**
+       * The world time when the active effect first started
+       * @defaultValue `null`
+       */
+      startTime: fields.NumberField<{ initial: null; label: "EFFECT.StartTime" }>;
+
+      /**
+       * The maximum duration of the effect, in seconds
+       * @defaultValue `null`
+       */
+      seconds: fields.NumberField<{ integer: true; min: 0; label: "EFFECT.DurationSecs" }>;
+
+      /**
+       * The _id of the CombatEncounter in which the effect first started
+       * @defaultValue `null`
+       */
+      combat: fields.ForeignDocumentField<typeof documents.BaseCombat, { label: "EFFECT.Combat" }>;
+
+      /**
+       * The maximum duration of the effect, in combat rounds
+       * @defaultValue `null`
+       */
+      rounds: fields.NumberField<{ integer: true; min: 0 }>;
+
+      /**
+       * The maximum duration of the effect, in combat turns
+       * @defaultValue `null`
+       */
+      turns: fields.NumberField<{ integer: true; min: 0; label: "EFFECT.DurationTurns" }>;
+
+      /**
+       * The round of the CombatEncounter in which the effect first started
+       * @defaultValue `null`
+       */
+      startRound: fields.NumberField<{ integer: true; min: 0 }>;
+
+      /**
+       * The turn of the CombatEncounter in which the effect first started
+       * @defaultValue `null`
+       */
+      startTurn: fields.NumberField<{ integer: true; min: 0; label: "EFFECT.StartTurns" }>;
+    }>;
+
+    /**
+     * The HTML text description for this ActiveEffect document.
+     * @defaultValue `""`
+     */
+    description: fields.HTMLField<{ label: "EFFECT.Description"; textSearch: true }>;
+
+    /**
+     * A UUID reference to the document from which this ActiveEffect originated
+     * @defaultValue `null`
+     */
+    origin: fields.StringField<{ nullable: true; blank: false; initial: null; label: "EFFECT.Origin" }>;
+
+    /**
+     * A color string which applies a tint to the ActiveEffect icon
+     * @defaultValue `"#ffffff"`
+     */
+    tint: fields.ColorField<{ nullable: false; initial: "#ffffff"; label: "EFFECT.IconTint" }>;
+
+    /**
+     * Does this ActiveEffect automatically transfer from an Item to an Actor?
+     * @defaultValue `false`
+     */
+    transfer: fields.BooleanField<{ initial: true; label: "EFFECT.Transfer" }>;
+
+    /**
+     * Special status IDs that pertain to this effect
+     * @defaultValue `[]`
+     */
+    statuses: fields.SetField<fields.StringField<{ required: true; blank: false }>>;
+
+    sort: fields.IntegerSortField;
+
+    /**
+     * An object of optional key/value flags
+     * @defaultValue `{}`
+     */
+    flags: fields.ObjectField.FlagsField<"ActiveEffect", InterfaceToObject<CoreFlags>>;
+
+    _stats: fields.DocumentStatsField;
+  }
+
+  interface CoreFlags {
+    core?: { statusId?: string; overlay?: boolean };
+  }
+}