@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.340.1

package/README.md

@@ -86,16 +86,19 @@ Add foundry-vtt-types to your types section in your `tsconfig.json`:
 {
   "compilerOptions": {
     "types": ["fvtt-types"],
-    "module": "esnext",
+    "target": "esnext",
     "moduleResolution": "bundler",
     "strict": true
   }
 }
 ```
 
-This will make the type definitions available globally in your project.
+Compiler Option Notes:
 
-We recommend using `"strict": true` 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` are the most important.
+- `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,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@league-of-foundry-developers/foundry-vtt-types",
-  "version": "13.340.0",
+  "version": "13.340.1",
   "description": "TypeScript type definitions for Foundry VTT",
   "type": "module",
   "types": "./index.d.mts",
@@ -25,17 +25,31 @@
       "types": "./src/foundry/public/scripts/workers/image-compressor.d.mts"
     }
   },
+  "imports": {
+    "#client/*": {
+      "import": "./src/foundry/client/*"
+    },
+    "#client-esm/*": {
+      "import": "./src/foundry/client-esm/*"
+    },
+    "#common/*": {
+      "import": "./src/foundry/common/*"
+    }
+  },
   "scripts": {
-    "lint": "npm-run-all -c typecheck lint/eslint lint/prettier",
-    "lint/eslint": "eslint --cache .",
-    "lint/prettier": "prettier -c .",
-    "lint:fix": "npm-run-all -c typecheck lint:fix/eslint lint:fix/prettier",
-    "lint:fix/eslint": "eslint --cache --fix .",
-    "lint:fix/prettier": "prettier -l -w .",
+    "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": "tsc -b tsconfig.main.json",
-    "prepare": "is-ci || husky"
+    "prepare": "is-ci || husky",
+    "betterer": "betterer",
+    "betterer:update": "betterer --update"
   },
   "repository": {
     "type": "git",
@@ -91,12 +105,12 @@
     "@types/showdown": "~2.0.6",
     "@types/simple-peer": "~9.11.1",
     "@types/youtube": "~0.0.48",
-    "earcut": "^3.0.1",
     "codemirror": "^6.0.1",
+    "earcut": "^3.0.1",
     "handlebars": "^4.7.8",
     "handlebars-intl": "^1.1.2",
     "jquery": "^3.7.1",
-    "mime-types": "^2.1.35",
+    "mime-types": "^3.0.1",
     "peggy": "^4.2.0",
     "pixi.js": "^7.4.2",
     "prosemirror-collab": "^1.3.1",
@@ -123,20 +137,25 @@
   "devDependencies": {
     "@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:.",
-    "@typescript-eslint/eslint-plugin": "^8.23.0",
-    "@typescript-eslint/parser": "^8.23.0",
-    "@typescript-eslint/utils": "^8.23.0",
+    "@types/picomatch": "^4.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.31.0",
+    "@typescript-eslint/parser": "^8.31.0",
+    "@typescript-eslint/scope-manager": "^8.31.0",
+    "@typescript-eslint/utils": "^8.31.0",
+    "enhanced-resolve": "^5.18.1",
     "eslint": "^9.19.0",
     "eslint-config-prettier": "^10.0.1",
-    "eslint-import-resolver-typescript": "^3.7.0",
+    "eslint-import-resolver-typescript": "^4.3.2",
     "eslint-plugin-import-x": "^4.6.1",
     "eslint-plugin-tsdoc": "^0.4.0",
-    "globals": "^15.14.0",
+    "globals": "^16.0.0",
     "husky": "^9.1.4",
     "is-ci": "^4.1.0",
     "lint-staged": "^15.3.0",
@@ -144,8 +163,8 @@
     "pathe": "^2.0.2",
     "prettier": "^3.0.3",
     "type-fest": "^4.34.0",
-    "typescript": "~5.7",
-    "typescript-eslint": "^8.23.0",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.31.0",
     "vitest": "^3.0.5"
   },
   "peerDependencies": {
@@ -160,7 +179,10 @@
   "files": [
     "index.d.mts",
     "index-lenient.d.mts",
-    "src"
+    "src",
+    "tsconfig.json",
+    "tsconfig.main.json",
+    "tsconfig.miscellaneous.json"
   ],
   "publishConfig": {
     "access": "public"

package/src/configuration/configuration.d.mts

@@ -3,7 +3,7 @@ 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}) are only initialized after certain events have happened during the
+ * 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.
  *
@@ -24,7 +24,7 @@ import type Document from "../foundry/common/abstract/document.d.mts";
  *
  * @example
  * ```typescript
- * declare global {
+ * declare module "fvtt-types/configuration" {
  *   interface AssumeHookRan {
  *     setup: never; // the type doesn't matter
  *   }
@@ -48,14 +48,14 @@ export interface AssumeHookRan {}
  * // myActor.ts
  * class MyActor extends Actor {}
  *
- * // entryPoint.ts
+ * // index.ts
  * import { MyActor } from "./myActor"
  *
- * hooks.once("init", () => {
+ * Hooks.once("init", () => {
  *   CONFIG.Actor.documentClass = typeof MyActor;
  * });
  *
- * declare global {
+ * declare module "fvtt-types/configuration" {
  *   interface DocumentClassConfig {
  *     Actor: typeof MyActor
  *   }
@@ -77,14 +77,14 @@ export interface DocumentClassConfig {}
  * // myToken.ts
  * class MyToken extends Token {}
  *
- * // entryPoint.ts
+ * // index.ts
  * import { MyToken } from "./myToken"
  *
  * Hooks.once("init", () => {
  *   CONFIG.Token.objectClass = MyToken;
  * });
  *
- * declare global {
+ * declare module "fvtt-types/configuration" {
  *   interface PlaceableObjectClassConfig {
  *     Token: typeof MyToken;
  *   }
@@ -95,9 +95,9 @@ export interface DocumentClassConfig {}
 export interface PlaceableObjectClassConfig {}
 
 /**
- * This interface together with {@link SourceConfig} is used to configure the
+ * 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} and {@link foundry.documents.BaseItem}
+ * {@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
@@ -145,7 +145,7 @@ export interface PlaceableObjectClassConfig {}
  * type MyItemDataSource = ArmorDataSource | WeaponDataSource;
  * type MyItemDataProperties = ArmorDataProperties | WeaponDataProperties;
  *
- * declare global {
+ * declare module "fvtt-types/configuration" {
  *   interface DataConfig {
  *     Item: MyItemDataProperties;
  *   }
@@ -161,11 +161,11 @@ export interface PlaceableObjectClassConfig {}
  *   damage: 5
  * });
  *
- * if(item.data.type === "weapon") {
+ * if (item.data.type === "weapon") {
  *   const damage: number = item.data.data.damage;
  * }
  *
- * if(item.data._source.type === "armor") {
+ * if (item.data._source.type === "armor") {
  *   const armorValue = item.data._source.data.armorValue;
  * }
  * ```
@@ -187,7 +187,7 @@ export interface GetDataConfig {}
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface DataModelConfig {}
 
-/** @see {@link DataConfig} */
+/** @see {@link DataConfig | `DataConfig`} */
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface SourceConfig {}
 
@@ -199,7 +199,7 @@ export interface WebRTCConfig {}
 
 /**
  * Injects extra data for modules from `game.modules.get("module-id")`.
- * @see {@link RequiredModules} for removing the `undefined` type for required modules.
+ * @see {@link RequiredModules | `RequiredModules`} for removing the `undefined` type for required modules.
  *  @example
  * ```typescript
  * interface ModuleConfig {
@@ -216,7 +216,7 @@ 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} for adding useful properties to the returned modules, like APIs.
+ * @see {@link ModuleConfig | `ModuleConfig`} for adding useful properties to the returned modules, like APIs.
  * @example
  * ```typescript
  * interface RequiredModules {
@@ -255,7 +255,9 @@ export interface SettingConfig {
   }>;
   "core.defaultDrawingConfig": MaybeEmpty<foundry.documents.BaseDrawing["_source"]>;
   "core.defaultToken": DeepPartial<foundry.documents.BaseToken>;
-  "core.diceConfiguration": Record<CONFIG.Dice.DTermDiceStrings, string>;
+  "core.diceConfiguration": {
+    [K in CONFIG.Dice.DTermDiceStrings]?: string | undefined;
+  };
   "core.disableResolutionScaling": boolean;
   "core.fontSize": number;
   "core.fpsMeter": boolean;
@@ -282,13 +284,12 @@ export interface SettingConfig {
     nullable: true;
     initial: null;
     choices: {
-      [_ in typeof CONST.CANVAS_PERFORMANCE_MODES.LOW]: "SETTINGS.PerformanceModeLow";
-    } & {
-      [_ in typeof CONST.CANVAS_PERFORMANCE_MODES.MED]: "SETTINGS.PerformanceModeMed";
-    } & {
-      [_ in typeof CONST.CANVAS_PERFORMANCE_MODES.HIGH]: "SETTINGS.PerformanceModeHigh";
-    } & {
-      [_ in typeof CONST.CANVAS_PERFORMANCE_MODES.MAX]: "SETTINGS.PerformanceModeMax";
+      // 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;

package/src/configuration/documents.d.mts

@@ -0,0 +1,295 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type, @typescript-eslint/no-unused-vars */
+
+/**
+ * Use this interface to configure your custom generic `ActiveEffect` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomActiveEffect<
+ *   SubType extends ActiveEffect.SubType
+ * > extends ActiveEffect<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredActiveEffect<SubType extends ActiveEffect.SubType> {
+ *     document: CustomActiveEffect<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredActiveEffect<SubType extends ActiveEffect.SubType> {}
+
+/**
+ * Use this interface to configure your custom generic `ActorDelta` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomActorDelta<
+ *   SubType extends ActorDelta.SubType
+ * > extends ActorDelta<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredActorDelta<SubType extends ActorDelta.SubType> {
+ *     document: CustomActorDelta<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredActorDelta<SubType extends ActorDelta.SubType> {}
+
+/**
+ * Use this interface to configure your custom generic `Actor` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomActor<
+ *   SubType extends Actor.SubType
+ * > extends Actor<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredActor<SubType extends Actor.SubType> {
+ *     document: CustomActor<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredActor<SubType extends Actor.SubType> {}
+
+/**
+ * Use this interface to configure your custom generic `Card` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomCard<
+ *   SubType extends Card.SubType
+ * > extends Card<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredCard<SubType extends Card.SubType> {
+ *     document: CustomCard<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredCard<SubType extends Card.SubType> {}
+
+/**
+ * Use this interface to configure your custom generic `Cards` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomCards<
+ *   SubType extends Cards.SubType
+ * > extends Cards<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredCards<SubType extends Cards.SubType> {
+ *     document: CustomCards<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredCards<SubType extends Cards.SubType> {}
+
+/**
+ * Use this interface to configure your custom generic `ChatMessage` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomChatMessage<
+ *   SubType extends ChatMessage.SubType
+ * > extends ChatMessage<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredChatMessage<SubType extends ChatMessage.SubType> {
+ *     document: CustomChatMessage<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredChatMessage<SubType extends ChatMessage.SubType> {}
+
+/**
+ * Use this interface to configure your custom generic `Combat` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomCombat<
+ *   SubType extends Combat.SubType
+ * > extends Combat<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredCombat<SubType extends Combat.SubType> {
+ *     document: CustomCombat<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredCombat<SubType extends Combat.SubType> {}
+
+/**
+ * Use this interface to configure your custom generic `Combatant` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomCombatant<
+ *   SubType extends Combatant.SubType
+ * > extends Combatant<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredCombatant<SubType extends Combatant.SubType> {
+ *     document: CustomCombatant<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredCombatant<SubType extends Combatant.SubType> {}
+
+/**
+ * Use this interface to configure your custom generic `Folder` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomFolder<
+ *   SubType extends Folder.SubType
+ * > extends Folder<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredFolder<SubType extends Folder.SubType> {
+ *     document: CustomFolder<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredFolder<SubType extends Folder.SubType> {}
+
+/**
+ * Use this interface to configure your custom generic `Item` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomItem<
+ *   SubType extends Item.SubType
+ * > extends Item<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredItem<SubType extends Item.SubType> {
+ *     document: CustomItem<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredItem<SubType extends Item.SubType> {}
+
+/**
+ * Use this interface to configure your custom generic `JournalEntryPage` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomJournalEntryPage<
+ *   SubType extends JournalEntryPage.SubType
+ * > extends JournalEntryPage<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredJournalEntryPage<SubType extends JournalEntryPage.SubType> {
+ *     document: CustomJournalEntryPage<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredJournalEntryPage<SubType extends JournalEntryPage.SubType> {}
+
+/**
+ * Use this interface to configure your custom generic `Macro` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomMacro<
+ *   SubType extends Macro.SubType
+ * > extends Macro<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredMacro<SubType extends Macro.SubType> {
+ *     document: CustomMacro<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredMacro<SubType extends Macro.SubType> {}
+
+/**
+ * Use this interface to configure your custom generic `RegionBehavior` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomRegionBehavior<
+ *   SubType extends RegionBehavior.SubType
+ * > extends RegionBehavior<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredRegionBehavior<SubType extends RegionBehavior.SubType> {
+ *     document: CustomRegionBehavior<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredRegionBehavior<SubType extends RegionBehavior.SubType> {}
+
+/**
+ * Use this interface to configure your custom generic `TableResult` implementation.
+ * See also {@link DocumentClassConfig | `DocumentClassConfig`} to configure your class.
+ *
+ * @example
+ * ```typescript
+ * class CustomTableResult<
+ *   SubType extends TableResult.SubType
+ * > extends TableResult<SubType> {
+ *   ...
+ * }
+ *
+ * declare module "fvtt-types/configuration" {
+ *   interface ConfiguredTableResult<SubType extends TableResult.SubType> {
+ *     document: CustomTableResult<SubType>;
+ *   }
+ * }
+ * ```
+ */
+export interface ConfiguredTableResult<SubType extends TableResult.SubType> {}

package/src/configuration/globals.d.mts

@@ -39,10 +39,8 @@ export import AlertPing = globalThis.AlertPing;
 export import AlphaBlurFilter = globalThis.AlphaBlurFilter;
 export import AlphaBlurFilterPass = globalThis.AlphaBlurFilterPass;
 export import AmbientLight = globalThis.AmbientLight;
-export import AmbientLightConfig = globalThis.AmbientLightConfig;
 export import AmbientLightDocument = globalThis.AmbientLightDocument;
 export import AmbientSound = globalThis.AmbientSound;
-export import AmbientSoundConfig = globalThis.AmbientSoundConfig;
 export import AmbientSoundDocument = globalThis.AmbientSoundDocument;
 export import AmplificationBackgroundVisionShader = globalThis.AmplificationBackgroundVisionShader;
 export import AmplificationSamplerShader = globalThis.AmplificationSamplerShader;
@@ -347,3 +345,11 @@ export import WorldSettings = globalThis.WorldSettings;
 export import foundry = globalThis.foundry;
 export import io = globalThis.io;
 export import tinyMCE = globalThis.tinyMCE;
+
+export import I18nInitGame = globalThis.I18nInitGame;
+export import InitGame = globalThis.InitGame;
+export import SetupGame = globalThis.SetupGame;
+export import ReadyGame = globalThis.ReadyGame;
+
+export import EarcutEdges = globalThis.EarcutEdges;
+export import PackageManifestData = globalThis.PackageManifestData;

package/src/configuration/index.d.mts

@@ -1,4 +1,5 @@
 /* eslint-disable import-x/extensions, import-x/export */
 
 export * from "./globals.mjs";
+export * from "./documents.mjs";
 export * from "./configuration.mjs";