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

package/src/foundry/common/abstract/type-data.d.mts

@@ -0,0 +1,343 @@
+import type { MustConform } from "../../../types/helperTypes.d.mts";
+import type {
+  AnyObject,
+  EmptyObject,
+  DeepPartial,
+  IsObject,
+  Merge,
+  RemoveIndexSignatures,
+  SimpleMerge,
+} from "../../../types/utils.d.mts";
+import type { SchemaField } from "../data/fields.d.mts";
+import type BaseUser from "../documents/user.d.mts";
+import type { DataModel } from "./data.d.mts";
+import type Document from "./document.d.mts";
+
+type StaticDataModel = typeof DataModel<DataSchema, Document<any, DataSchema, any>>;
+
+interface _InternalTypeDataModelInterface extends StaticDataModel {
+  new <Schema extends DataSchema, Parent extends Document.Any, _ComputedInstance extends DataModel<Schema, Parent>>(
+    ...args: ConstructorParameters<typeof DataModel<Schema, Parent>>
+  ): _ComputedInstance;
+}
+
+declare const _InternalTypeDataModelConst: _InternalTypeDataModelInterface;
+
+// @ts-expect-error Ignore the error, this is a workaround for a dynamic class.
+declare class _InternalTypeDataModel<
+  Schema extends DataSchema,
+  Parent extends Document<any, DataSchema, any>,
+  BaseData extends AnyObject = EmptyObject,
+  DerivedData extends AnyObject = EmptyObject,
+  // This does not work if inlined. It's weird to put it here but it works.
+  _ComputedInstance extends DataModel<Schema, Parent> = SimpleMerge<
+    Merge<RemoveIndexSignatures<BaseData>, RemoveIndexSignatures<DerivedData>>,
+    // The merge is written this way because properties in the data model _cannot_ be allowed to be overridden by the base or derived data.
+    // In theory this could be allowed but it causes a few difficulties.
+    // The fundamental issue is that allowing this would cause subclasses to no longer guaranteed to be valid subtypes.
+    // A particularly thorny but not fully fundamental issue is that it also causes difficulties with `this` inside of classes generic over `BaseData`.
+    DataModel<Schema, Parent>
+  >,
+> extends _InternalTypeDataModelConst<Schema, Parent, _ComputedInstance> {}
+
+declare const __TypeDataModelBrand: unique symbol;
+
+// These properties are used to give a performant way of inferring types like `BaseData` and `DerivedData` types.
+// This avoids checking the entire constraint `T extends TypeDataModel.Any` to infer out the types.
+// To prevent adding properties that could appear at runtime they are unique symbols.
+// This makes them uniterable and means that the only way to access them is to have a reference to the variables which will be impossible outside of this file.
+declare const __Schema: unique symbol;
+declare const __Parent: unique symbol;
+declare const __BaseModel: unique symbol;
+declare const __BaseData: unique symbol;
+declare const __DerivedData: unique symbol;
+
+type _ClassMustBeAssignableToInternal = MustConform<typeof Document, Document.Internal.Constructor>;
+type _InstanceMustBeAssignableToInternal = MustConform<Document.Any, Document.Internal.Instance.Any>;
+
+// Removes the base and derived data from the type.
+// Has no extends bounds to simplify any checking logic.
+type RemoveDerived<BaseThis, BaseModel, BaseData, DerivedData> = SimpleMerge<
+  Omit<BaseThis, keyof BaseData | keyof DerivedData>,
+  BaseModel
+>;
+
+// Merges U into T but makes the appropriate keys partial.
+// This is similar to `Merge<T, DeepPartial<U>>` but only makes the deepest keys in `U` optional.
+type MergePartial<T, U> = Omit<T, keyof U> & {
+  [K in keyof U as K extends PartialMergeKeys<T, U> ? K : never]?: InnerMerge<U, K, T>;
+} & {
+  [K in keyof U as K extends PartialMergeKeys<T, U> ? never : K]: InnerMerge<U, K, T>;
+};
+
+// Note(LukeAbby): The addition of `PropertyKey` seems to help simplify tsc's type checking.
+// This will likely not be necessary after
+type RequiredKeys<T> = PropertyKey &
+  {
+    [K in keyof T]-?: T extends { readonly [_ in K]: any } ? K : never;
+  }[keyof T];
+
+// Returns all the keys of U that should be partial when merged into T.
+// Only if both `T[K]` and `U[K]` are required and both are objects should a key be required.
+// This is because essentially only the most deep keys that are merged in need to be optional.
+//
+// Note(LukeAbby): The addition of `PropertyKey` seems to help simplify tsc's type checking.
+type PartialMergeKeys<T, U> = PropertyKey &
+  {
+    [K in keyof U]-?: K extends RequiredKeys<U>
+      ? K extends RequiredKeys<T>
+        ? IsObject<T[K]> extends true
+          ? IsObject<U[K]> extends true
+            ? never
+            : K
+          : K
+        : K
+      : K;
+  }[keyof U];
+
+// Merges `U[K]` into `T[K]` if they're both objects, returns `U[K]` otherwise.
+type InnerMerge<U, K extends keyof U, T> = T extends { readonly [_ in K]?: infer V }
+  ? IsObject<U[K]> extends true
+    ? IsObject<V> extends true
+      ? MergePartial<V, U[K]>
+      : Partial<U[K]>
+    : Partial<U[K]>
+  : U[K];
+
+declare namespace TypeDataModel {
+  type Any = TypeDataModel<any, any, any, any>;
+
+  // Documented at https://gist.github.com/LukeAbby/c7420b053d881db4a4d4496b95995c98
+  namespace Internal {
+    type Constructor = (abstract new (arg0: never, ...args: never[]) => Instance.Any) & {
+      [__TypeDataModelBrand]: never;
+    };
+
+    // This still is only allows instances descended from `TypeDataField` because these unique symbols aren't used elsewhere.
+    // These generic parameters seem to be required. This is likely because of a TypeScript soundness holes in which concrete types like `any` or `unknown`
+    // will get treated bivariantly whereas type parameters get treated more safely.
+    interface Instance<
+      out Schema extends DataSchema,
+      out Parent extends Document.Any,
+      out BaseModel,
+      out BaseData,
+      out DerivedData,
+    > {
+      [__Schema]: Schema;
+      [__Parent]: Parent;
+      [__BaseModel]: BaseModel;
+      [__BaseData]: BaseData;
+      [__DerivedData]: DerivedData;
+    }
+
+    namespace Instance {
+      type Any = Instance<any, any, any, any, any>;
+    }
+  }
+
+  type PrepareBaseDataThis<BaseThis extends Internal.Instance.Any> =
+    BaseThis extends Internal.Instance<any, any, infer BaseModel, infer BaseData, infer DerivedData>
+      ? MergePartial<Omit<RemoveDerived<BaseThis, BaseModel, BaseData, DerivedData>, "prepareBaseData">, BaseData>
+      : never;
+
+  type PrepareDerivedDataThis<BaseThis extends Internal.Instance.Any> =
+    BaseThis extends Internal.Instance<any, any, infer BaseModel, infer BaseData, infer DerivedData>
+      ? MergePartial<
+          SimpleMerge<Omit<RemoveDerived<BaseThis, BaseModel, BaseData, DerivedData>, "prepareDerivedData">, BaseData>,
+          DerivedData
+        >
+      : never;
+
+  type ParentAssignmentType<BaseThis extends Internal.Instance.Any> =
+    BaseThis extends Internal.Instance<infer Schema, infer Parent, any, any, any>
+      ? SimpleMerge<
+          SchemaField.InitializedType<Document.SchemaFor<Parent>>,
+          {
+            // FIXME(LukeAbby): Callers handle making this partial when obvious.
+            // However also should make system partial using the regular rules: if `initial` is assignable to the field or if `required` is false etc.
+            system: SchemaField.InitializedType<Schema>;
+          }
+        >
+      : never;
+}
+
+/**
+ * A specialized subclass of DataModel, intended to represent a Document's type-specific data.
+ * Systems or Modules that provide DataModel implementations for sub-types of Documents (such as Actors or Items)
+ * should subclass this class instead of the base DataModel class.
+ *
+ *
+ * @example Registering a custom sub-type for a Module.
+ *
+ * **module.json**
+ * ```json
+ * {
+ *   "id": "my-module",
+ *   "esmodules": ["main.mjs"],
+ *   "documentTypes": {
+ *     "Actor": {
+ *       "sidekick": {},
+ *       "villain": {}
+ *     },
+ *     "JournalEntryPage": {
+ *       "dossier": {},
+ *       "quest": {
+ *         "htmlFields": ["description"]
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * **main.mjs**
+ * ```js
+ * Hooks.on("init", () => {
+ *   Object.assign(CONFIG.Actor.dataModels, {
+ *     "my-module.sidekick": SidekickModel,
+ *     "my-module.villain": VillainModel
+ *   });
+ *   Object.assign(CONFIG.JournalEntryPage.dataModels, {
+ *     "my-module.dossier": DossierModel,
+ *     "my-module.quest": QuestModel
+ *   });
+ * });
+ *
+ * class QuestModel extends foundry.abstract.TypeDataModel {
+ *   static defineSchema() {
+ *     const fields = foundry.data.fields;
+ *     return {
+ *       description: new fields.HTMLField({required: false, blank: true, initial: ""}),
+ *       steps: new fields.ArrayField(new fields.StringField())
+ *     };
+ *   }
+ *
+ *   prepareDerivedData() {
+ *     this.totalSteps = this.steps.length;
+ *   }
+ * }
+ * ```
+ */
+declare abstract class TypeDataModel<
+  Schema extends DataSchema,
+  Parent extends Document.Any,
+  BaseData extends AnyObject = EmptyObject,
+  DerivedData extends AnyObject = EmptyObject,
+> extends _InternalTypeDataModel<Schema, Parent, BaseData, DerivedData> {
+  static [__TypeDataModelBrand]: never;
+
+  [__Schema]: Schema;
+  [__Parent]: Parent;
+  [__BaseModel]: DataModel<Schema, Parent>;
+  [__BaseData]: RemoveIndexSignatures<BaseData>;
+  [__DerivedData]: RemoveIndexSignatures<DerivedData>;
+
+  modelProvider: System | Module | null;
+
+  /**
+   * A set of localization prefix paths which are used by this data model.
+   */
+  static LOCALIZATION_PREFIXES: string[];
+
+  /**
+   * Prepare data related to this DataModel itself, before any derived data is computed.
+   *
+   * Called before {@link ClientDocument#prepareBaseData} in {@link ClientDocument#prepareData}.
+   * */
+  prepareBaseData(this: TypeDataModel.PrepareBaseDataThis<this>): void;
+
+  /**
+   * Apply transformations of derivations to the values of the source data object.
+   * Compute data fields whose values are not stored to the database.
+   *
+   * Called before {@link ClientDocument#prepareDerivedData} in {@link ClientDocument#prepareData}.
+   */
+  prepareDerivedData(this: TypeDataModel.PrepareDerivedDataThis<this>): void;
+
+  /**
+   * Convert this Document to some HTML display for embedding purposes.
+   * @param config  - Configuration for embedding behavior.
+   * @param options - The original enrichment options for cases where the Document embed content
+   *                  also contains text that must be enriched.
+   */
+  toEmbed(
+    config: TextEditor.DocumentHTMLEmbedConfig,
+    options: TextEditor.EnrichmentOptions,
+  ): Promise<HTMLElement | HTMLCollection | null>;
+
+  /* -------------------------------------------- */
+  /*  Database Operations                         */
+  /* -------------------------------------------- */
+
+  /**
+   * Called by {@link ClientDocument#_preCreate}.
+   *
+   * @param data    - The initial data object provided to the document creation request
+   * @param options - Additional options which modify the creation request
+   * @param user    - The User requesting the document creation
+   * @returns Return false to exclude this Document from the creation operation
+   */
+  protected _preCreate(
+    data: TypeDataModel.ParentAssignmentType<this>,
+    options: Document.PreCreateOptions<any>,
+    user: BaseUser,
+  ): Promise<boolean | void>;
+
+  /**
+   * Called by {@link ClientDocument#_onCreate}.
+   *
+   * @param data    - The initial data object provided to the document creation request
+   * @param options - Additional options which modify the creation request
+   * @param userId  - The id of the User requesting the document update
+   */
+  protected _onCreate(
+    data: TypeDataModel.ParentAssignmentType<this>,
+    options: Document.OnCreateOptions<any>,
+    userId: string,
+  ): void;
+
+  /**
+   * Called by {@link ClientDocument#_preUpdate}.
+   *
+   * @param changes - The candidate changes to the Document
+   * @param options - Additional options which modify the update request
+   * @param user    - The User requesting the document update
+   * @returns A return value of false indicates the update operation should be cancelled.
+   */
+  protected _preUpdate(
+    changes: DeepPartial<TypeDataModel.ParentAssignmentType<this>>,
+    options: Document.PreUpdateOptions<any>,
+    userId: string,
+  ): Promise<boolean | void>;
+
+  /**
+   * Called by {@link ClientDocument#_onUpdate}.
+   *
+   * @param changed - The differential data that was changed relative to the documents prior values
+   * @param options - Additional options which modify the update request
+   * @param userId  - The id of the User requesting the document update
+   */
+  protected _onUpdate(
+    changed: DeepPartial<TypeDataModel.ParentAssignmentType<this>>,
+    options: Document.OnUpdateOptions<any>,
+    userId: string,
+  ): void;
+
+  /**
+   * Called by {@link ClientDocument#_preDelete}.
+   *
+   * @param options - Additional options which modify the deletion request
+   * @param user    - The User requesting the document deletion
+   * @returns A return value of false indicates the deletion operation should be cancelled.
+   */
+  protected _preDelete(options: Document.PreDeleteOptions<any>, user: BaseUser): Promise<boolean | void>;
+
+  /**
+   * Called by {@link ClientDocument#_onDelete}.
+   *
+   * @param options - Additional options which modify the deletion request
+   * @param userId  - The id of the User requesting the document update
+   */
+  protected _onDelete(options: Document.OnDeleteOptions<any>, userId: string): void;
+}
+
+export default TypeDataModel;

package/src/foundry/common/config.d.mts

@@ -0,0 +1,302 @@
+import type { DataModel } from "./abstract/data.d.mts";
+import type * as fields from "./data/fields.d.mts";
+import type { SOFTWARE_UPDATE_CHANNELS } from "./constants.d.mts";
+import type { AnyObject } from "../../types/utils.d.mts";
+
+declare namespace ApplicationConfiguration {
+  interface Schema extends DataSchema {
+    /**
+     * The server administrator password (obscured)
+     */
+    adminPassword: fields.StringField<{
+      required: true;
+      blank: false;
+      nullable: true;
+      initial: null;
+      label: "SETUP.AdminPasswordLabel";
+      hint: "SETUP.AdminPasswordHint";
+    }>;
+
+    /**
+     * The relative path (to Config) of an AWS configuration file
+     */
+    awsConfig: fields.StringField<{
+      label: "SETUP.AWSLabel";
+      hint: "SETUP.AWSHint";
+      blank: false;
+      nullable: true;
+      initial: null;
+    }>;
+
+    /**
+     * Whether to compress static files? True by default
+     */
+    compressStatic: fields.BooleanField<{
+      initial: true;
+      label: "SETUP.CompressStaticLabel";
+      hint: "SETUP.CompressStaticHint";
+    }>;
+
+    compressSocket: fields.BooleanField<{
+      initial: true;
+      label: "SETUP.CompressSocketLabel";
+      hint: "SETUP.CompressSocketHint";
+    }>;
+
+    cssTheme: fields.StringField<{
+      blank: false;
+      choices: typeof foundry.CONST.CSS_THEMES;
+      initial: "foundry";
+      label: "SETUP.CSSTheme";
+      hint: "SETUP.CSSThemeHint";
+    }>;
+
+    /**
+     * The absolute path of the user data directory (obscured)
+     */
+    dataPath: fields.StringField<{ label: "SETUP.DataPathLabel"; hint: "SETUP.DataPathHint" }>;
+
+    deleteNEDB: fields.BooleanField<{ label: "SETUP.DeleteNEDBLabel"; hint: "SETUP.DeleteNEDBHint" }>;
+
+    /**
+     * Whether the application should automatically start in fullscreen mode?
+     */
+    fullscreen: fields.BooleanField<{ initial: false }>;
+
+    /**
+     * A custom hostname applied to internet invitation addresses and URLs
+     */
+    hostname: fields.StringField<{ required: true; blank: false; nullable: true; initial: null }>;
+
+    hotReload: fields.BooleanField<{ initial: false; label: "SETUP.HotReloadLabel"; hint: "SETUP.HotReloadHint" }>;
+
+    /**
+     * The default language for the application
+     */
+    language: fields.StringField<{
+      required: true;
+      blank: false;
+      initial: "en.core";
+      label: "SETUP.DefaultLanguageLabel";
+      hint: "SETUP.DefaultLanguageHint";
+    }>;
+
+    /**
+     * A custom hostname applied to local invitation addresses
+     */
+    localHostname: fields.StringField<{ required: true; blank: false; nullable: true; initial: null }>;
+
+    /**
+     * A custom salt used for hashing user passwords (obscured)
+     */
+    passwordSalt: fields.StringField<{ required: true; blank: false; nullable: true; initial: null }>;
+
+    /**
+     * The port on which the server is listening
+     */
+    port: fields.NumberField<{
+      required: true;
+      nullable: false;
+      integer: true;
+      initial: 30000;
+      validate: typeof ApplicationConfiguration._validatePort;
+      label: "SETUP.PortLabel";
+      hint: "SETUP.PortHint";
+    }>;
+
+    /**
+     * The Internet Protocol version to use, either 4 or 6.
+     */
+    protocol: fields.NumberField<{ integer: true; choices: [4, 6]; nullable: true }>;
+
+    /**
+     * An external-facing proxied port used for invitation addresses and URLs
+     */
+    proxyPort: fields.NumberField<{ required: true; nullable: true; integer: true; initial: null }>;
+
+    /**
+     * Is the application running in SSL mode at a reverse-proxy level?
+     */
+    proxySSL: fields.BooleanField<{ initial: false }>;
+
+    /**
+     * A URL path part which prefixes normal application routing
+     */
+    routePrefix: fields.StringField<{ required: true; blank: false; nullable: true; initial: null }>;
+
+    /**
+     * The relative path (to Config) of a used SSL certificate
+     */
+    sslCert: fields.StringField<{
+      label: "SETUP.SSLCertLabel";
+      hint: "SETUP.SSLCertHint";
+      blank: false;
+      nullable: true;
+      initial: null;
+    }>;
+
+    /**
+     * The relative path (to Config) of a used SSL key
+     */
+    sslKey: fields.StringField<{ label: "SETUP.SSLKeyLabel"; blank: false; nullable: true; initial: null }>;
+
+    telemetry: fields.BooleanField<{
+      required: false;
+      initial: undefined;
+      label: "SETUP.Telemetry";
+      hint: "SETUP.TelemetryHint";
+    }>;
+
+    /**
+     * The current application update channel
+     */
+    updateChannel: fields.StringField<{
+      required: true;
+      choices: typeof foundry.CONST.SOFTWARE_UPDATE_CHANNELS;
+      initial: "stable";
+    }>;
+
+    /**
+     * Is UPNP activated?
+     */
+    upnp: fields.BooleanField<{ initial: true }>;
+
+    /**
+     * The duration in seconds of a UPNP lease, if UPNP is active
+     */
+    upnpLeaseDuration: fields.NumberField;
+
+    /**
+     * A default world name which starts automatically on launch
+     */
+    world: fields.StringField<{
+      required: true;
+      blank: false;
+      nullable: true;
+      initial: null;
+      label: "SETUP.WorldLabel";
+      hint: "SETUP.WorldHint";
+    }>;
+
+    noBackups: fields.BooleanField<{ required: false }>;
+  }
+}
+
+/**
+ * A data model definition which describes the application configuration options.
+ * These options are persisted in the user data Config folder in the options.json file.
+ * The server-side software extends this class and provides additional validations and
+ * @remarks yes the description really does cut off
+ */
+declare class ApplicationConfiguration extends DataModel<ApplicationConfiguration.Schema> {
+  static defineSchema(): ApplicationConfiguration.Schema;
+
+  static override migrateData(source: AnyObject): AnyObject;
+
+  /**
+   * Validate a port assignment.
+   * @param port - The requested port
+   * @throws An error if the requested port is invalid
+   * @throws `The application port must be an integer, either 80, 443, or between 1024 and 65535`
+   */
+  static _validatePort(port: number): void;
+}
+
+declare namespace ReleaseData {
+  interface Schema extends DataSchema {
+    /**
+     * The major generation of the Release
+     */
+    generation: fields.NumberField<{
+      required: true;
+      nullable: false;
+      integer: true;
+      min: 1;
+    }>;
+
+    /**
+     * The maximum available generation of the software.
+     */
+    maxGeneration: fields.NumberField<{
+      required: false;
+      nullable: false;
+      integer: true;
+      min: 1;
+      // initial: () => fields.SchemaField.InnerInitializedType<Schema["generation"]>;
+    }>;
+
+    /**
+     * The maximum available stable generation of the software.
+     */
+    maxStableGeneration: fields.NumberField<{
+      required: false;
+      nullable: false;
+      integer: true;
+      min: 1;
+      // initial: () => fields.SchemaField.InitializedType<Schema["generation"]>;
+    }>;
+    channel: fields.StringField<{ choices: typeof SOFTWARE_UPDATE_CHANNELS; blank: false }>;
+
+    /**
+     * An optional appended string display for the Release
+     */
+    suffix: fields.StringField;
+
+    /**
+     * The internal build number for the Release
+     */
+    build: fields.NumberField<{ required: true; nullable: false; integer: true }>;
+
+    /**
+     * When the Release was released
+     */
+    time: fields.NumberField<{ nullable: false; initial: typeof Date.now }>;
+
+    /**
+     * The minimum required Node.js major version
+     */
+    node_version: fields.NumberField<{ required: true; nullable: false; integer: true; min: 10 }>;
+
+    /**
+     * Release notes for the update version
+     */
+    notes: fields.StringField;
+
+    /**
+     * A temporary download URL where this version may be obtained
+     */
+    download: fields.StringField;
+  }
+}
+
+/** A data object which represents the details of this Release of Foundry VTT */
+declare class ReleaseData extends DataModel<ReleaseData.Schema> {
+  static defineSchema(): ReleaseData.Schema;
+
+  /** A formatted string for shortened display, such as "Version 9" */
+  get shortDisplay(): string;
+
+  /** A formatted string for general display, such as "V9 Prototype 1" or "Version 9" */
+  get display(): string;
+
+  /** A formatted string for Version compatibility checking, such as "9.150" */
+  get version(): string;
+
+  override toString(): this["shortDisplay"];
+
+  /**
+   * 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;
+}
+
+export { ApplicationConfiguration, ReleaseData };