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

package/README.md

@@ -19,18 +19,20 @@ At the moment, versions 0.7, 0.8, and 9 are fully supported with partial support
 
 ## V12 Installation
 
-Currently v12 is still in beta. There are known bugs, issues in the ergonomics, and major unfinished work in the current implementation. To get a direct line of communication about the current status of development as well as to help us understand what areas need to be prioritizated first, join the [League of Extraordinary FoundryVTT Developers Discord](https://discord.gg/73HTMuK7dT) or file an issue.
+Currently v12 is still in beta. There are known bugs, issues in the ergonomics, and major unfinished work in the current implementation. To get a direct line of communication about the current status of development as well as to help us understand what areas need to be prioritized first, join the [League of Extraordinary FoundryVTT Developers Discord](https://discord.gg/73HTMuK7dT) or file an issue.
 
 The recommended way to install for v12 is this command:
 
 ```sh
-npm add --include=dev github:League-of-Foundry-Developers/foundry-vtt-types#main
+npm add -D fvtt-types@github:League-of-Foundry-Developers/foundry-vtt-types#main
 ```
 
-Alternatively, if you're using yarn you'll need to use the command `yarn add --dev foundry-vtt-types@github:League-of-Foundry-Developers/foundry-vtt-types#main`.
+Alternatively, if you're using yarn you'll need to use the command `yarn add --dev fvtt-types@github:League-of-Foundry-Developers/foundry-vtt-types#main`.
 
 This will add the current commit on `main` as a dependency. Both npm and yarn's lockfile will store the commit you initially installed this command and so updates to your dependency will not happen automatically or even after a fresh install. To update you will need to be rerun the prior command periodically to update as improvements are added frequently.
 
+If you've been using the types for a few months now, the best branch would be `maintenance` instead. `main` will have a number of backwards incompatible breaking changes going forward.
+
 ## Installation
 
 You can install historical versions of foundry-vtt-types from the [npm registry](https://npmjs.org/).
@@ -38,19 +40,19 @@ You can install historical versions of foundry-vtt-types from the [npm registry]
 In order to install the latest stable version (v9), run
 
 ```sh
-npm install --save-dev @league-of-foundry-developers/foundry-vtt-types
+npm add --save-dev fvtt-types@npm:@league-of-foundry-developers/foundry-vtt-types
 ```
 
 In order to install a specific version run
 
 ```sh
-npm install --save-dev @league-of-foundry-developers/foundry-vtt-types@<version>
+npm add --save-dev fvtt-types@npm:@league-of-foundry-developers/foundry-vtt-types@<version>
 ```
 
 For example, to install version `9.268.0`, run
 
 ```sh
-npm install --save-dev @league-of-foundry-developers/foundry-vtt-types@9.268.0
+npm add --save-dev fvtt-types@npm:@league-of-foundry-developers/foundry-vtt-types@9.268.0
 ```
 
 You can then update foundry-vtt-types using the regular update mechanism for npm
@@ -83,23 +85,20 @@ Add foundry-vtt-types to your types section in your `tsconfig.json`:
 ```json
 {
   "compilerOptions": {
-    "types": ["@league-of-foundry-developers/foundry-vtt-types"],
-    "module": "node16",
-    "moduleResolution": "node16",
-    "esModuleInterop": true,
-    "strictNullChecks": true
+    "types": ["fvtt-types"],
+    "target": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true
   }
 }
 ```
 
-This will make the type definitions available globally in your project.
-
-Make sure you are using at least `"module": "node16"` and `"moduleResolution": "node16"`, too. It is required for some
-imports to be resolved correctly, such as `@league-of-foundry-developers/foundry-vtt-types/src/types/utils.mts`.
+Compiler Option Notes:
 
-Also make sure to set `"strictNullChecks": true` because otherwise, some conditional types used in the type definitions
-resolve incorrectly, and you will see a lot of errors. Alternatively, you can just set `"strict": true`, which
-implicitly sets `strictNullChecks`. This is actually what we **recommend**, but it's not required.
+- `types` is set to make fvtt-types globally available in your project. Without it global variables like `game` and `CONFIG` won't appear.
+- `"target": "esnext"` is recommended because Foundry lives on the bleeding edge of JavaScript features. If you want to downlevel your code setting `"lib": ["esnext", "dom"]` and `target` is reasonable but TypeScript's downlevelling is not the most advanced and so it's probably a good idea to leave this to other tools. It's a bad idea to lower the `lib` version as Foundry will frequently use new JavaScript features. Nevertheless the minimum out of the box usable lib is `es2022` as before that types like `WeakRef` won't exist.
+- Using `"strict": true` is _highly_ recommended because it enables a whole host of useful options. However if you want to check that your config supports foundry-vtt-types, the most important settings under `strict` would be `strictNullChecks` and `strictFunctionTypes`.
+- Changing the `moduleResolution` is generally not recommended. Only new `moduleResolution` strategies have support for certain imports like `"fvtt-types/utils"`. For example the Node `moduleResolutions` above `node16` may work but have additional Node-only constraints not relevant to the browser.
 
 You can find some information about how to actually work with the type definitions in the
 [Wiki](https://github.com/League-of-Foundry-Developers/foundry-vtt-types/wiki). A good starting point is

package/package.json

@@ -1,25 +1,53 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@league-of-foundry-developers/foundry-vtt-types",
-  "version": "12.331.2-beta",
+  "version": "12.331.4-beta",
   "description": "TypeScript type definitions for Foundry VTT",
   "type": "module",
   "types": "./index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.mts"
+    },
+    "./lenient": {
+      "types": "./src/index-lenient.d.mts"
+    },
+    "./utils": {
+      "types": "./src/utils/index.d.mts"
+    },
+    "./configuration": {
+      "types": "./src/configuration/index.d.mts"
+    },
+    "./worker": {
+      "types": "./src/foundry/public/scripts/workers/index.d.mts"
+    },
+    "./worker/image-compressor": {
+      "types": "./src/foundry/public/scripts/workers/image-compressor.d.mts"
+    }
+  },
   "scripts": {
-    "lint": "./node_modules/typescript/bin/tsc; eslint .",
-    "lint:fix": "eslint --fix .",
-    "lint:ci": "eslint .",
-    "eslint:report": "eslint --output-file eslint_report.json --format json .",
+    "format": "prettier -l -w .",
+    "lint": "npm-run-all -c typecheck eslint prettier",
+    "eslint": "eslint --cache .",
+    "prettier": "prettier -c .",
+    "lint:fix": "npm-run-all -c typecheck eslint:fix prettier:fix",
+    "eslint:fix": "eslint --cache --fix .",
+    "prettier:fix": "prettier -l -w .",
+    "eslint:report": "eslint --cache --output-file eslint_report.json --format json .",
     "test": "vitest --typecheck",
-    "typecheck": "./node_modules/typescript/bin/tsc",
+    "typecheck": "tsc -b tsconfig.main.json",
     "prepare": "is-ci || husky",
-    "postinstall": "patch-package"
+    "betterer": "betterer",
+    "betterer:update": "betterer --update"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/League-of-Foundry-Developers/foundry-vtt-types"
   },
   "contributors": [
+    {
+      "name": "LukeAbby"
+    },
     {
       "name": "Kai Moschcau"
     },
@@ -54,14 +82,16 @@
     "typescript"
   ],
   "dependencies": {
+    "@pixi/basis": "^7.4.2",
     "@pixi/graphics-smooth": "^1.1.0",
     "@pixi/particle-emitter": "^5.0.8",
+    "@types/earcut": "^3.0.0",
     "@types/jquery": "~3.5.22",
     "@types/showdown": "~2.0.6",
     "@types/simple-peer": "~9.11.1",
     "@types/youtube": "~0.0.48",
+    "earcut": "^3.0.1",
     "handlebars": "^4.7.8",
-    "patch-package": "^8.0.0",
     "pixi.js": "^7.4.2",
     "postinstall-postinstall": "^2.1.0",
     "prosemirror-collab": "^1.3.1",
@@ -81,46 +111,57 @@
     "tinymce": "^6.8.3"
   },
   "devDependencies": {
-    "@fvtt-types/fvtt-types": "file:.",
-    "@typescript-eslint/eslint-plugin": "^8.12.2",
-    "@typescript-eslint/parser": "^8.12.2",
-    "eslint": "^8.57.1",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-import-resolver-typescript": "^3.6.1",
-    "eslint-plugin-import": "^2.29.1",
+    "@actions/core": "^1.11.1",
+    "@actions/github": "^6.0.0",
+    "@betterer/betterer": "^6.0.0-alpha.1",
+    "@betterer/cli": "^6.0.0-alpha.1",
+    "@eslint/compat": "^1.2.6",
+    "@eslint/js": "^9.19.0",
+    "@ts-morph/common": "^0.26.1",
+    "@types/debug": "^4.1.12",
+    "@types/fvtt-types": "file:.",
+    "@types/picomatch": "^4.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.26.1",
+    "@typescript-eslint/parser": "^8.23.0",
+    "@typescript-eslint/scope-manager": "^8.27.0",
+    "@typescript-eslint/utils": "^8.26.1",
+    "enhanced-resolve": "^5.18.1",
+    "eslint": "^9.19.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-import-resolver-typescript": "^4.3.2",
+    "eslint-plugin-import-x": "^4.6.1",
     "eslint-plugin-tsdoc": "^0.4.0",
+    "globals": "^16.0.0",
     "husky": "^9.1.4",
     "is-ci": "^4.1.0",
-    "lint-staged": "^15.2.10",
+    "lint-staged": "^15.3.0",
+    "npm-run-all": "^4.1.5",
+    "pathe": "^2.0.2",
     "prettier": "^3.0.3",
-    "typescript": "~5.7",
-    "vitest": "^2.1.4"
+    "type-fest": "^4.34.0",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.26.1",
+    "vitest": "^3.0.5"
   },
   "peerDependencies": {
     "typescript": "^5.4"
   },
   "overrides": {
-    "@types/css-font-loading-module": "^0.0.12s"
-  },
-  "resolutions": {
-    "@types/earcut": "patch:@types/earcut@2.1.4#./patches/@types+earcut+2.1.4.patch"
-  },
-  "husky": {
-    "hooks": {
-      "pre-commit": "lint-staged"
+    "@types/css-font-loading-module": "^0.0.14",
+    "@pixi/utils": {
+      "@types/earcut": "3.0.0"
     }
   },
-  "lint-staged": {
-    "*.(d.mts|test-d.ts)": "eslint --fix",
-    "*.(js|json|yml)": "prettier --write"
-  },
   "files": [
     "index.d.mts",
     "index-lenient.d.mts",
-    "src"
+    "src",
+    "tsconfig.json",
+    "tsconfig.main.json",
+    "tsconfig.miscellaneous.json"
   ],
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
+  "packageManager": "npm@10.8.1"
 }

package/src/configuration/configuration.d.mts

@@ -0,0 +1,316 @@
+import type { DeepPartial, MaybeEmpty } from "fvtt-types/utils";
+import type { fields } from "../foundry/common/data/module.d.mts";
+import type Document from "../foundry/common/abstract/document.d.mts";
+
+/**
+ * Some global variables (such as {@link game | `game`}) are only initialized after certain events have happened during the
+ * initialization of Foundry VTT. For that reason, the correct types for these variables include the types for the
+ * uninitialized state.
+ *
+ * While this is correct from a type checking perspective, it can be inconvenient to have to type guard these global
+ * variables everywhere. Some users might prefer the convenience over the 100% correctness in type checking.
+ *
+ * For this reason, this interface provides a way for users to configure certain global variables to be typed more
+ * leniently, i.e., as the types of their initialized state. This is done via declaration merging. To do so merge in
+ * a property with the name of the event that should be assumed to have been run.
+ *
+ * The currently supported hooks are:
+ * - init
+ * - i18nInit
+ * - setup
+ * - ready
+ *
+ * You can also set the special key "none" to make the default behavior set the variable to `undefined` instead of a union.
+ *
+ * @example
+ * ```typescript
+ * declare module "fvtt-types/configuration" {
+ *   interface AssumeHookRan {
+ *     setup: never; // the type doesn't matter
+ *   }
+ * }
+ *
+ * const referenceToGame: Game = game; // ok! :)
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface AssumeHookRan {}
+
+/**
+ * This interface is used to configure the used document classes at a type
+ * level. Module and system authors should use declaration merging to provide
+ * the types of their configured document classes. It is extremely important
+ * that this is kept in sync with the configuration that actually happens at
+ * runtime.
+ *
+ * @example
+ * ```typescript
+ * // myActor.ts
+ * class MyActor extends Actor {}
+ *
+ * // entryPoint.ts
+ * import { MyActor } from "./myActor"
+ *
+ * hooks.once("init", () => {
+ *   CONFIG.Actor.documentClass = typeof MyActor;
+ * });
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface DocumentClassConfig {
+ *     Actor: typeof MyActor
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface DocumentClassConfig {}
+
+/**
+ * This interface is used to configure the used object classes at a type
+ * level. Module and system authors should use declaration merging to provide
+ * the types of their configured object classes. It is extremely important
+ * that this is kept in sync with the configuration that actually happens at
+ * runtime.
+ *
+ * @example
+ * ```typescript
+ * // myToken.ts
+ * class MyToken extends Token {}
+ *
+ * // entryPoint.ts
+ * import { MyToken } from "./myToken"
+ *
+ * Hooks.once("init", () => {
+ *   CONFIG.Token.objectClass = MyToken;
+ * });
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface PlaceableObjectClassConfig {
+ *     Token: typeof MyToken;
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface PlaceableObjectClassConfig {}
+
+/**
+ * This interface together with {@link SourceConfig | `SourceConfig`} is used to configure the
+ * types of the `data`  and `data._source` properties of the
+ * {@link foundry.documents.BaseActor | `foundry.documents.BaseActor`} and {@link foundry.documents.BaseItem | `foundry.documents.BaseItem`}
+ * classes. System authors should use declaration merging to provide the types
+ * that match their `template.json` file. It is also very important for these
+ * types to stay in sync with the `template.json` file, otherwise unexpected
+ * runtime errors might appear.
+ *
+ * @example
+ * ```typescript
+ * interface ArmorDataSourceData {
+ *   armorValue: number;
+ * }
+ *
+ * interface ArmorDataSource {
+ *   type: "armor";
+ *   data: ArmorDataSourceData;
+ * }
+ *
+ * interface WeaponDataSourceData {
+ *   damagePerHit: number;
+ *   attackSpeed: number;
+ * }
+ *
+ * interface WeaponDataSource {
+ *   type: "weapon";
+ *   data: WeaponDataSourceData;
+ * }
+ *
+ * interface ArmorDataPropertiesData extends ArmorDataSourceData {
+ *   weight: number;
+ * }
+ *
+ * interface ArmorDataProperties {
+ *   type: "armor";
+ *   data: ArmorDataPropertiesData;
+ * }
+ *
+ * interface WeaponDataPropertiesData extends WeaponDataSourceData {
+ *   damage: number;
+ * }
+ *
+ * interface WeaponDataProperties {
+ *   type: "weapon";
+ *   data: WeaponDataPropertiesData;
+ * }
+ *
+ * type MyItemDataSource = ArmorDataSource | WeaponDataSource;
+ * type MyItemDataProperties = ArmorDataProperties | WeaponDataProperties;
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface DataConfig {
+ *     Item: MyItemDataProperties;
+ *   }
+ *
+ *   interface SourceConfig {
+ *     Item: MyItemDataSource;
+ *   }
+ * }
+ * const item = await Item.create({
+ *   name: "Axe",
+ *   type: "weapon",
+ *   attackSpeed: 1,
+ *   damage: 5
+ * });
+ *
+ * if (item.data.type === "weapon") {
+ *   const damage: number = item.data.data.damage;
+ * }
+ *
+ * if (item.data._source.type === "armor") {
+ *   const armorValue = item.data._source.data.armorValue;
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface DataConfig {}
+
+/**
+ * Configure the return type of the `getData` method for AppV1 Applications.
+ *
+ * mode - The mode of the return type.
+ * - if mode is "partial", the return type is a partial of the data object, and will allow for any Record\<string,unknown\> to be returned, regardless of the actual data object.
+ * - if mode is "exact", the return type is the exact data object, and will not allow for any additional properties to be returned.
+ * - if mode is "object", the return type is a generic object, and will allow for any object to be returned, regardless of the actual data object.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface GetDataConfig {}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface DataModelConfig {}
+
+/** @see {@link DataConfig | `DataConfig`} */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface SourceConfig {}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface FlagConfig {}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface WebRTCConfig {}
+
+/**
+ * Injects extra data for modules from `game.modules.get("module-id")`.
+ * @see {@link RequiredModules | `RequiredModules`} for removing the `undefined` type for required modules.
+ *  @example
+ * ```typescript
+ * interface ModuleConfig {
+ *   "module-id": {
+ *     api: APIObject;
+ *   };
+ * }
+ * const moduleApi: APIObject | undefined = game.modules.get("module-id")?.api;
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface ModuleConfig {}
+
+/**
+ * Removes `undefined` for modules listed as keys here from the return type of `game.modules.get`.
+ * Useful if a module is a required dependency.
+ * @see {@link ModuleConfig | `ModuleConfig`} for adding useful properties to the returned modules, like APIs.
+ * @example
+ * ```typescript
+ * interface RequiredModules {
+ *   "module-id": true;
+ * }
+ * const module: Game.ModuleData<foundry.packages.ModuleData> = game.modules.get("module-id");
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RequiredModules {}
+
+export interface SettingConfig {
+  "core.animateRollTable": boolean;
+  "core.chatBubbles": fields.BooleanField<{ initial: true }>;
+  "core.chatBubblesPan": fields.BooleanField<{ initial: true }>;
+  "core.combatTrackerConfig": MaybeEmpty<{ resource: string; skipDefeated: boolean }>;
+  "core.compendiumConfiguration": Partial<Record<string, CompendiumCollection.Configuration>>;
+  "core.coneTemplateType": "round" | "flat";
+  "core.colorSchema": fields.StringField<{
+    required: true;
+    blank: true;
+    initial: "";
+    choices: {
+      "": "SETTINGS.ColorSchemeDefault";
+      dark: "SETTINGS.ColorSchemeDark";
+      light: "SETTINGS.ColorSchemeLight";
+    };
+  }>;
+  "core.combatTheme": fields.StringField<{
+    required: true;
+    blank: false;
+    initial: "none";
+    choices: () => {
+      [K in keyof CONFIG.Combat.Sounds]: string;
+    };
+  }>;
+  "core.defaultDrawingConfig": MaybeEmpty<foundry.documents.BaseDrawing["_source"]>;
+  "core.defaultToken": DeepPartial<foundry.documents.BaseToken>;
+  "core.diceConfiguration": {
+    [K in CONFIG.Dice.DTermDiceStrings]?: string | undefined;
+  };
+  "core.disableResolutionScaling": boolean;
+  "core.fontSize": number;
+  "core.fpsMeter": boolean;
+  "core.globalAmbientVolume": number;
+  "core.globalInterfaceVolume": number;
+  "core.globalPlaylistVolume": number;
+  "core.keybindings": Record<string, ClientKeybindings.KeybindingActionBinding[]>;
+  "core.language": fields.StringField<{
+    required: true;
+    blank: false;
+    initial: NonNullable<typeof game.i18n>["lang"];
+    choices: typeof CONFIG.supportedLanguages;
+  }>;
+  "core.leftClickRelease": fields.BooleanField<{ initial: true }>;
+  "core.lightAnimation": boolean;
+  "core.maxFPS": number;
+  "core.mipmap": boolean;
+  "core.moduleConfiguration": Record<string, boolean>;
+  "core.noCanvas": fields.BooleanField<{ initial: false }>;
+  "core.notesDisplayToggle": boolean;
+  "core.nue.shownTips": boolean;
+  "core.performanceMode": fields.NumberField<{
+    required: true;
+    nullable: true;
+    initial: null;
+    choices: {
+      // Note: these keys correspond to values of `CANVAS_PERFORMANCE_MODES`. They are not used
+      // directly because the values are branded.
+      0: "SETTINGS.PerformanceModeLow";
+      1: "SETTINGS.PerformanceModeMed";
+      2: "SETTINGS.PerformanceModeHigh";
+      3: "SETTINGS.PerformanceModeMax";
+    };
+  }>;
+  "core.permissions": Game.Permissions;
+  "core.pixelRatioResolutionScaling": fields.BooleanField<{ initial: true }>;
+  "core.playlist.playingLocation": "top" | "bottom";
+  "core.rollMode": fields.StringField<{
+    required: true;
+    blank: false;
+    initial: typeof CONST.DICE_ROLL_MODES.PUBLIC;
+    choices: typeof CONFIG.Dice.rollModes;
+  }>;
+  "core.rtcClientSettings": typeof AVSettings.DEFAULT_CLIENT_SETTINGS;
+  "core.rtcWorldSettings": typeof AVSettings.DEFAULT_WORLD_SETTINGS;
+  "core.scrollingStatusText": fields.BooleanField<{ initial: true }>;
+  "core.sheetClasses": {
+    [Key in Document.Type as Document.SubTypesOf<Key> extends string ? Key : never]?: Record<
+      Document.SubTypesOf<Key> & string,
+      string
+    >;
+  };
+  "core.time": fields.NumberField<{ required: true; nullable: false; initial: 0 }>;
+  "core.tokenDragPreview": boolean;
+  "core.visionAnimation": boolean;
+}