@league-of-foundry-developers/foundry-vtt-types 0.8.9-6 → 9.238.0

package/README.md

@@ -2,47 +2,64 @@
 
 <div align=center>
 
+<img align=center src="./media/img/league-logo-ts.svg" alt="League Logo TS" width="150"/>
+
 TypeScript type definitions for [Foundry Virtual Tabletop](https://foundryvtt.com/) (unofficial)
 
 [![League Discord Server](https://img.shields.io/discord/732325252788387980?label=League%20of%20Extraordinary%20Foundry%20VTT%20Developers)](https://discord.gg/52DNPzqm2Z)
-![GitHub 0.7.x issues by-label](https://img.shields.io/github/issues-raw/League-of-Foundry-Developers/foundry-vtt-types/foundry%200.7.x?color=%23fe631d)
-![GitHub closed 0.7.x issues by-label](https://img.shields.io/github/issues-closed-raw/League-of-Foundry-Developers/foundry-vtt-types/foundry%200.7.x?color=%23fe631d)
-![GitHub 0.8.x issues by-label](https://img.shields.io/github/issues-raw/League-of-Foundry-Developers/foundry-vtt-types/foundry%200.8.x?color=%23fe631d)
-![GitHub closed 0.8.x issues by-label](https://img.shields.io/github/issues-closed-raw/League-of-Foundry-Developers/foundry-vtt-types/foundry%200.8.x?color=%23fe631d)
+![GitHub V9 issues by-label](https://img.shields.io/github/issues-raw/League-of-Foundry-Developers/foundry-vtt-types/foundry%20V9?color=%23fe631d)
+![GitHub closed V9 issues by-label](https://img.shields.io/github/issues-closed-raw/League-of-Foundry-Developers/foundry-vtt-types/foundry%20V9?color=%23fe631d)
 [![npm (tag)](https://img.shields.io/npm/v/@league-of-foundry-developers/foundry-vtt-types/latest)](https://www.npmjs.com/package/@league-of-foundry-developers/foundry-vtt-types)
 
 </div>
 
 ## Supported Foundry VTT versions
 
-We aim to support the latest patch release of minor versions of Foundry VTT, starting with 0.7.
+We aim to support the latest release of each Foundry VTT version (0.7, 0.8, 9, etc.), starting with 0.7.
+
+At the moment, both version 0.7 and 0.8 are supported. Work on support for version 9 is in progress.
 
-At the moment, the latest 0.7.x and 0.8.x versions are supported. However, note that work on 0.8.x has not been
-completed yet, so there are still quite a few things which are either missing or typed incorrectly. Take a look at
-[0.8.x issues](https://github.com/League-of-Foundry-Developers/foundry-vtt-types/issues?q=is%3Aopen+is%3Aissue+label%3A%22foundry+0.8.x%22)
-to see what still needs to be done.
 
 ## Installation
 
-You can install foundry-vtt-types from the [npm registry](https://npmjs.org/). We provide distribution tags for the
-different supported Foundry VTT versions that have the form `fvtt-<foundry-version>`. For example, the distribution tag
-for Foundry VTT 0.8.8 is `fvtt-0.8.8`.
+You can install foundry-vtt-types from the [npm registry](https://npmjs.org/).
 
-In order to install the desired version, run
+In order to install the latest version, run
 
 ```sh
-npm install --save-dev @league-of-foundry-developers/foundry-vtt-types@fvtt-<foundry-version>
+npm install --save-dev @league-of-foundry-developers/foundry-vtt-types
 ```
 
-For example, to install the type definitions for Foundry VTT 0.8.8 run
+In order to install a specific version run
 
 ```sh
-npm install --save-dev @league-of-foundry-developers/foundry-vtt-types@fvtt-0.8.8
+npm install --save-dev @league-of-foundry-developers/foundry-vtt-types@<version>
+```
+
+For example, to install version `0.8.9-9`, run
+
+```sh
+npm install --save-dev @league-of-foundry-developers/foundry-vtt-types@0.8.9-9
 ```
 
 You can then update foundry-vtt-types using the regular update mechanism for npm
 (see [npm update](https://docs.npmjs.com/cli/v7/commands/npm-update)).
 
+## Versioning scheme
+
+The versions of the foundry-vtt-types correspond to the releases of Foundry VTT. The versioning scheme of Foundry VTT
+changed with version 9, so the versioning scheme for the foundry-vtt-types also changes with that version:
+* For Foundry VTT version 0.7 and 0.8, the versioning scheme is
+  ```
+  0.<foundy-minor-version>.<foundry-patch-version>-<increment>
+  ```
+* For Foundry VTT version 9 and onwards, the versioning scheme is
+  ```
+  <foundry-version>.<foundry-build>.<increment>
+  ```
+In both cases, `increment` is a number that increases with every individual release of the foundry-vtt-types for that
+Foundry VTT release.
+
 ## Usage
 
 Add foundry-vtt-types to your types section in your `tsconfig.json`:
@@ -62,13 +79,13 @@ This will make the type definitions available globally in your project.
 Make sure you are using `"moduleResolution": "node"`, too. It is required for some dependencies to be resolved
 correctly.
 
-Also make sure to set `"strictNullChecks": true` because otherwise, some of the conditional types used in the type
-definitions resolve incorrectly and you will see a lot of errors.
+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.
 
 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). If you are working with Foundry VTT
-0.8.x, a good starting point is
-[[0.8.x] FAQ](https://github.com/League-of-Foundry-Developers/foundry-vtt-types/wiki/%5B0.8.x%5D-FAQ).
+[Wiki](https://github.com/League-of-Foundry-Developers/foundry-vtt-types/wiki). A good starting point is
+the [FAQ](https://github.com/League-of-Foundry-Developers/foundry-vtt-types/wiki/FAQ).
 
 ## Acknowledgments
 
@@ -80,10 +97,10 @@ by [@NickEastNL](https://gitlab.com/NvanOosten)
 Contributions are very welcome in order to decrease the individual workload. Filing issues for wrong / missing types is
 also a great way to help us improve the type definitions.
 
-There are individual branches for the different supported Foundry VTT versions that are being worked on. They are named
-according to the minor version of the Foundry VTT version, e.g. the branch for Foundry VTT 0.8 is called
-`foundry-0.8.x`. All work to improve the type definitions for a specific version needs to be done through Pull Requests
-to the corresponding branch.
+Development on the current version of Foundry VTT is done on the `main` branch. Additionally, we keep branches for the
+older version of Foundry VTT that we still support. These branches are named according to the Foundry VTT version they
+correspond to. For example, the branch for Foundry VTT 0.8 is called `foundry-0.8.x`. All work to improve the type
+definitions needs to be done through Pull Requests to the relevant branch.
 
 Please read [CONTRIBUTING.md](CONTRIBUTING.md) for more details on how to contribute.
 
@@ -92,7 +109,7 @@ If you have any specific questions, feel free to contact us in the
 
 ## Type-Checking, Linting, Testing
 
-When contributing, make sure sure that the type checks pass, the linter is green and the tests are green. We _do_ have
+When contributing, make sure that the type checks pass, the linter is green and the tests are green. We _do_ have
 checks in the CI but running this locally also helps you while developing and saves you time as you don't have to wait
 for the CI.
 
@@ -114,7 +131,7 @@ To create a release, you have to create a new release commit, tag it and create
 handle the rest.
 
 ```
-npm version prerelease
+npm version <release-type>
 git push --follow-tags
 ```
 

package/index-lenient.d.ts

@@ -0,0 +1,10 @@
+import './index';
+
+declare global {
+  interface LenientGlobalVariableTypes {
+    canvas: never;
+    game: never;
+    socket: never;
+    ui: never;
+  }
+}

package/index.d.ts

@@ -1,4 +1,4 @@
-import 'jquery';
-import 'handlebars';
 import 'pixi.js';
 import './src';
+import 'handlebars';
+import 'jquery';

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@league-of-foundry-developers/foundry-vtt-types",
-  "version": "0.8.9-6",
+  "version": "9.238.0",
   "description": "TypeScript type definitions for Foundry VTT",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts"
+    },
+    "./lenient": {
+      "types": "./index-lenient.d.ts"
+    }
+  },
   "scripts": {
     "lint": "./node_modules/typescript/bin/tsc && eslint --ext .d.ts,.test-d.ts .",
     "lint:fix": "eslint --fix --ext .d.ts,.test-d.ts .",
@@ -15,7 +23,26 @@
     "type": "git",
     "url": "https://github.com/League-of-Foundry-Developers/foundry-vtt-types"
   },
-  "author": "Kai Moschcau",
+  "contributors": [
+    {
+      "name": "Kai Moschcau"
+    },
+    {
+      "name": "Johannes Loher"
+    },
+    {
+      "name": "Oskar Pfeifer-Bley"
+    },
+    {
+      "name": "FloRad"
+    },
+    {
+      "name": "NickEastNL"
+    },
+    {
+      "name": "BoltsJ"
+    }
+  ],
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/League-of-Foundry-Developers/foundry-vtt-types/issues"
@@ -28,26 +55,26 @@
     "typscript"
   ],
   "dependencies": {
-    "@types/jquery": "~3.5.6",
+    "@types/jquery": "~3.5.9",
     "@types/simple-peer": "~9.11.1",
     "handlebars": "4.7.7",
     "pixi-particles": "4.3.1",
-    "pixi.js": "5.3.4",
-    "socket.io-client": "4.1.2",
-    "tinymce": "5.8.1"
+    "pixi.js": "5.3.11",
+    "socket.io-client": "4.3.2",
+    "tinymce": "5.10.1"
   },
   "devDependencies": {
-    "@typescript-eslint/eslint-plugin": "^4.28.3",
-    "@typescript-eslint/parser": "^4.28.3",
-    "eslint": "^7.30.0",
+    "@typescript-eslint/eslint-plugin": "^5.5.0",
+    "@typescript-eslint/parser": "^5.5.0",
+    "eslint": "^8.4.0",
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-prettier": "^4.0.0",
     "eslint-plugin-tsdoc": "^0.2.14",
-    "husky": "^7.0.1",
-    "lint-staged": "^11.0.1",
-    "prettier": "^2.3.2",
-    "tsd": "^0.17.0",
-    "typescript": "^4.4.3"
+    "husky": "^7.0.4",
+    "lint-staged": "^12.1.2",
+    "prettier": "^2.5.1",
+    "tsd": "~0.18.0",
+    "typescript": "~4.5.3"
   },
   "husky": {
     "hooks": {
@@ -56,10 +83,11 @@
   },
   "lint-staged": {
     "*.(d.ts|test-d.ts)": "eslint --fix",
-    "*.(js|json)": "prettier --write"
+    "*.(js|json|yml)": "prettier --write"
   },
   "files": [
     "index.d.ts",
+    "index-lenient.d.ts",
     "src"
   ],
   "publishConfig": {

package/src/foundry/common/abstract/backend.mjs.d.ts

@@ -27,22 +27,28 @@ declare abstract class DatabaseBackend {
 
   /**
    * Get primary Document instances
+   * @remarks
+   * foundry actually declares this function to take parameters `documentClass`, `query`, `options`, and `user` but
+   * that's not how it is called and also not how the subclasses implement it.
+   * See https://gitlab.com/foundrynet/foundryvtt/-/issues/6177
    */
   protected abstract _getDocuments<T extends Document<any, any>>(
     documentClass: ConstructorOf<T>,
-    query: Request,
-    options: RequestOptions,
+    request: Request,
     user: BaseUser
   ): Promise<T[]>;
 
   /**
    * Get embedded Document instances
+   * @remarks
+   * foundry actually declares this function to take parameters `documentClass`, `parent`, `query`, `options`, and
+   * `user` but that's not how it is called and also not how the subclasses implement it.
+   * See https://gitlab.com/foundrynet/foundryvtt/-/issues/6177
    */
   protected abstract _getEmbeddedDocuments<T extends Document<any, any>>(
     documentClass: ConstructorOf<T>,
     parent: T extends Document<any, infer U> ? U : never,
-    query: Request,
-    options: RequestOptions,
+    request: Request,
     user: BaseUser
   ): Promise<T[]>;
 
@@ -198,7 +204,8 @@ declare abstract class DatabaseBackend {
    * @param action    - The action performed
    * @param type      - The document type
    * @param documents - The documents modified
-   * @param info      - The logging level
+   * @param level     - The logging level
+   *                    (default: `'info'`)
    * @param parent    - A parent document
    * @param pack      - A compendium pack within which the operation occurred
    */
@@ -225,24 +232,16 @@ declare abstract class DatabaseBackend {
   protected _logContext({ parent, pack }?: { parent?: Document<any, any>; pack?: string }): string;
 }
 
-interface Request {
+export interface Request {
   data?: AnyDocumentData[];
   updates?: AnyDocumentData[];
   ids?: string[];
   parent?: Document<any, any>;
-  query?: object | IdQuery | SceneIdUserQuery;
+  query?: Record<string, unknown>;
   options?: RequestOptions;
   pack?: string;
 }
 
-export interface IdQuery {
-  _id: string;
-}
-export interface SceneIdUserQuery {
-  sceneId: string;
-  user: string;
-}
-
 export interface RequestOptions {
   index?: boolean;
   broadcast?: boolean;

package/src/foundry/common/abstract/document.mjs.d.ts

@@ -1,5 +1,4 @@
 import { BaseUser } from '../documents.mjs';
-import DatabaseBackend from './backend.mjs';
 import { AnyDocumentData } from './data.mjs';
 import {
   ConfiguredDocumentClass,
@@ -82,7 +81,7 @@ declare abstract class Document<
   /**
    * The database backend used to execute operations and handle results
    */
-  static get database(): DatabaseBackend; // TODO: Reference type defined in CONFIG
+  static get database(): CONFIG['DatabaseBackend'];
 
   /**
    * Return a reference to the implemented subclass of this base document type.
@@ -125,7 +124,7 @@ declare abstract class Document<
   get name(): string | null;
 
   /**
-   * Test whether a given User has a sufficient role in order to create Documents of this type.
+   * Test whether a given User has a sufficient role in order to create Documents of this type in general.
    * @param user - The User being tested
    * @returns Does the User have a sufficient role to create?
    */
@@ -138,35 +137,35 @@ declare abstract class Document<
    *                 (default: `{}`)
    * @param save   - Save the clone to the World database?
    *                 (default: `false`)
-   * @param keepId - Keep the original Document ID? Otherwise the ID will become undefined
-   *                 (default: `false`)
+   * @param context - Additional context options passed to the create method
+   *                 (default: `{}`)
    * @returns The cloned Document instance
    */
   clone(
     data?: DeepPartial<
       ConstructorDataType<ConcreteDocumentData> | (ConstructorDataType<ConcreteDocumentData> & Record<string, unknown>)
     >,
-    { save, keepId }?: { save?: boolean; keepId?: boolean }
+    { save, ...context }?: { save: boolean } & DocumentModificationContext
   ): TemporaryDocument<this> | Promise<TemporaryDocument<this> | undefined>;
 
   /**
-   * Get the permission level that a specific User has over this Document, a value in CONST.ENTITY_PERMISSIONS.
+   * Get the permission level that a specific User has over this Document, a value in CONST.DOCUMENT_PERMISSION_LEVELS.
    * @param user - The User being tested
-   * @returns A numeric permission level from CONST.ENTITY_PERMISSIONS or null
+   * @returns A numeric permission level from CONST.DOCUMENT_PERMISSION_LEVELS or null
    */
-  getUserLevel(user: BaseUser): foundry.CONST.EntityPermission | null;
+  getUserLevel(user: BaseUser): foundry.CONST.DOCUMENT_PERMISSION_LEVELS | null;
 
   /**
    * Test whether a certain User has a requested permission level (or greater) over the Document
    * @param user       - The User being tested
-   * @param permission - The permission level from ENTITY_PERMISSIONS to test
+   * @param permission - The permission level from DOCUMENT_PERMISSION_LEVELS to test
    * @param exact      - Require the exact permission level requested?
    *                     (default: `false`)
    * @returns Does the user have this permission level over the Document?
    */
   testUserPermission(
     user: BaseUser,
-    permission: keyof typeof foundry.CONST.ENTITY_PERMISSIONS | foundry.CONST.EntityPermission,
+    permission: keyof typeof foundry.CONST.DOCUMENT_PERMISSION_LEVELS | foundry.CONST.DOCUMENT_PERMISSION_LEVELS,
     { exact }?: { exact?: boolean }
   ): boolean;
 
@@ -688,6 +687,13 @@ declare abstract class Document<
   toJSON(): this['id'] extends string
     ? ReturnType<ConcreteDocumentData['toJSON']> & { _id: string }
     : ReturnType<ConcreteDocumentData['toJSON']>;
+
+  /**
+   * For Documents which include game system data, migrate the system data object to conform to its latest data model.
+   * The data model is defined by the template.json specification included by the game system.
+   * @returns The migrated system data object
+   */
+  migrateSystemData(): object;
 }
 
 export interface DocumentModificationOptions {
@@ -703,12 +709,23 @@ export interface DocumentModificationOptions {
    */
   index?: boolean;
 
+  /**
+   * An array of fields to retrieve when indexing the collection
+   */
+  indexFields?: string[];
+
   /**
    * When performing a creation operation, keep the provided _id instead of clearing it.
    * @defaultValue `false`
    */
   keepId?: boolean;
 
+  /**
+   * When performing a creation operation, keep existing _id values of documents embedded within the one being created instead of generating new ones.
+   * @defaultValue `true`
+   */
+  keepEmbeddedIds?: boolean;
+
   /**
    * Create a temporary document which is not saved to the database. Only used during creation.
    * @defaultValue `false`
@@ -780,7 +797,8 @@ export interface Metadata<ConcreteDocument extends Document<any, any>> {
   name: DocumentType;
   collection: string;
   label: string;
-  types: string[] | Record<string, unknown>; // TODO: Record<string, unknown> is only there because In BaseTableResult this is set to CONST.TABLE_RESULT_TYPES, check if this is a bug in foundry
+  labelPlural: string; // This is not set for the Document class but every class that implements Document actually provides it.
+  types: readonly string[];
   embedded: Record<string, ConstructorOf<Document<any, any>>>;
   hasSystemData: boolean;
   permissions: {

package/src/foundry/common/config.mjs/index.d.ts

@@ -0,0 +1 @@
+export { ReleaseData } from './releaseData';

package/src/foundry/common/config.mjs/releaseData.d.ts

@@ -0,0 +1,98 @@
+import { PropertiesToSource } from '../../../types/helperTypes';
+import { DocumentData } from '../abstract/module.mjs';
+import * as fields from '../data/fields.mjs';
+
+export interface ReleaseDataSchema extends DocumentSchema {
+  generation: typeof fields.REQUIRED_NUMBER;
+  channel: typeof fields.REQUIRED_STRING;
+  suffix: typeof fields.STRING_FIELD;
+  build: typeof fields.REQUIRED_NUMBER;
+  time: typeof fields.TIMESTAMP_FIELD;
+  node_version: typeof fields.POSITIVE_INTEGER_FIELD;
+  notes: typeof fields.BLANK_STRING;
+  download: typeof fields.BLANK_STRING;
+}
+
+export interface ReleaseDataProperties {
+  /** The major generation of the Release */
+  generation: number;
+
+  /** The channel the Release belongs to, such as "stable" */
+  channel: string;
+
+  /** An optional appended string display for the Release */
+  suffix: string | undefined;
+
+  /** The internal build number for the Release */
+  build: number;
+
+  /** When the Release was released */
+  time: number | undefined;
+
+  /** The minimum required Node.js major version */
+  node_version: number | undefined;
+
+  /** Release notes for the update version */
+  notes: string;
+
+  /** A temporary download URL where this version may be obtained */
+  download: string;
+}
+
+export interface ReleaseDataConstructorData {
+  /** The major generation of the Release */
+  generation?: number | undefined | null;
+
+  /** The channel the Release belongs to, such as "stable" */
+  channel: string;
+
+  /** An optional appended string display for the Release */
+  suffix?: string | undefined | null;
+
+  /** The internal build number for the Release */
+  build?: number | undefined | null;
+
+  /** When the Release was released */
+  time?: number | undefined | null;
+
+  /** The minimum required Node.js major version */
+  node_version?: number | undefined | null;
+
+  /** Release notes for the update version */
+  notes?: string | undefined | null;
+
+  /** A temporary download URL where this version may be obtained */
+  download?: string | undefined | null;
+}
+
+/** A data object which represents the details of this Release of Foundry VTT */
+export declare class ReleaseData<
+  Schema extends ReleaseDataSchema = ReleaseDataSchema,
+  Properties extends ReleaseDataProperties = ReleaseDataProperties,
+  ConstructorData extends ReleaseDataConstructorData = ReleaseDataConstructorData
+> extends DocumentData<Schema, Properties, PropertiesToSource<ReleaseDataProperties>, ConstructorData> {
+  static defineSchema(): ReleaseDataSchema;
+
+  /** A formatted string for shortened display, such as "Version 9" */
+  get shortDisplay(): string;
+
+  /** A formatted string for general display, such as "V9 Prototype 1" */
+  get display(): string;
+
+  /** A formatted string for Version compatibility checking, such as "9.150" */
+  get version(): string;
+
+  /**
+   * Is this ReleaseData object newer than some other version?
+   * @param other - Some other version to compare against
+   * @returns Is this ReleaseData a newer version?
+   */
+  isNewer(other: string | ReleaseData): boolean;
+
+  /**
+   * Is this ReleaseData object a newer generation than some other version?
+   * @param other - Some other version to compare against
+   * @returns Is this ReleaseData a newer generation?
+   */
+  isGenerationalChange(other: string | ReleaseData): boolean;
+}