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

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

@@ -1,9 +1,9 @@
-import type { AnyMutableObject, AnyObject, EmptyObject, Identity } from "fvtt-types/utils";
+import type { AnyMutableObject, AnyObject, EmptyObject, Identity, NullishProps } from "#utils";
 import type { DataField, SchemaField } from "../data/fields.d.mts";
 import type { fields } from "../data/module.d.mts";
 import type { DataModelValidationFailure } from "../data/validation-failure.d.mts";
 
-type DataSchema = foundry.data.fields.DataSchema;
+type DataSchema = fields.DataSchema;
 
 declare const DynamicClass: new <_Computed extends object>(...args: never) => _Computed;
 
@@ -30,7 +30,7 @@ declare abstract class DataModel<
    *                  will be owned by the constructed model instance and may be mutated.
    * @param options - Options which affect DataModel construction
    */
-  constructor(...args: DataModel.ConstructorArgs<Schema, Parent>);
+  constructor(...args: DataModel.ConstructorArgs<Schema, Parent, ExtraConstructorOptions>);
 
   /** @internal */
   " __fvtt_types_internal_source_data": SchemaField.SourceData<Schema>;
@@ -44,7 +44,8 @@ declare abstract class DataModel<
   /**
    * Configure the data model instance before validation and initialization workflows are performed.
    */
-  protected _configure(options?: ExtraConstructorOptions): void;
+  // options: not null (parameter default only, destructured in Document)
+  protected _configure(options?: DataModel.ConfigureOptions & ExtraConstructorOptions): void;
 
   /**
    * The source data object for this DataModel instance.
@@ -106,10 +107,12 @@ declare abstract class DataModel<
    * @param options - Options provided to the model constructor
    *                  (unused)
    * @returns Migrated and cleaned source data which will be stored to the model instance
+   * @remarks `options` is unused in `DataModel`
    */
+  // options: not null (parameter default only)
   protected _initializeSource(
     data: fields.SchemaField.CreateData<Schema> | this,
-    options?: Omit<DataModel.DataValidationOptions, "parent">,
+    options?: DataModel.InitializeSourceOptions & ExtraConstructorOptions,
   ): fields.SchemaField.SourceData<Schema>;
 
   /**
@@ -118,7 +121,7 @@ declare abstract class DataModel<
    * @param options - Additional options which are passed to field cleaning methods
    * @returns The cleaned source data
    */
-  static cleanData(source?: AnyMutableObject, options?: Parameters<SchemaField.Any["clean"]>[1]): AnyMutableObject;
+  static cleanData(source?: AnyMutableObject, options?: DataField.CleanOptions): AnyMutableObject;
 
   /**
    * A generator that orders the DataFields in the DataSchema into an expected initialization order.
@@ -129,9 +132,10 @@ declare abstract class DataModel<
    * Initialize the instance by copying data from the source object to instance attributes.
    * This mirrors the workflow of SchemaField#initialize but with some added functionality.
    * @param options - Options provided to the model constructor
-   *                  (unused)
+   * @remarks `options` gets passed on to each field in the schema's `#initialize`
    */
-  protected _initialize(options?: any): void;
+  // options: not null (parameter default only)
+  protected _initialize(options?: DataModel.InitializeOptions & ExtraConstructorOptions): void;
 
   /**
    * Reset the state of this data instance back to mirror the contained source data, erasing any changes.
@@ -142,9 +146,22 @@ declare abstract class DataModel<
    * Clone a model, creating a new data model by combining current data with provided overrides.
    * @param data    - Additional data which overrides current document data at the time of creation
    * @param context - Context options passed to the data model constructor
-   * @returns The cloned Document instance
+   * @returns The cloned Document [sic] instance
+   * @remarks Obviously returns not necessarily a `Document`, just a `DataModel`.
+   *
+   * **NOTE:** At the type level, the returned model will necessarily have the same parent as the instance `#clone()` is being called
+   * on; Accurate typing of `#parent` requires a cast.
+   * @privateRemarks Foundry types `context` as simply `object`, but going by core usage, it's a
+   * {@link DataModel.ConstructionContext | `DataModel.ConstructionContext`}. Both the implementation here
+   * and the override in `Document` provide `this.parent` to the construction context; Here, `context` is
+   * spread in, so providing a different parent is allowed. The `Document` override enforces `this.parent`
+   * with no opportunity to pass an alternative.
    */
-  clone(data?: fields.SchemaField.AssignmentData<Schema>, context?: DataModel.DataValidationOptions<Parent>): this;
+  // null would be fine for either/both params here, but it breaks Document, and its never *expected*, just incidentally doesn't break
+  clone(
+    data?: fields.SchemaField.AssignmentData<Schema>,
+    context?: DataModel.CloneContext & ExtraConstructorOptions,
+  ): this;
 
   /**
    * Validate the data contained in the document to check for type and content
@@ -153,7 +170,8 @@ declare abstract class DataModel<
    * @param options - Optional parameters which customize how validation occurs.
    * @returns An indicator for whether the document contains valid data
    */
-  validate({ changes, clean, fallback, strict, fields, joint }?: DataModel.ValidateOptions<Schema>): boolean;
+  // options: not null (destructured)
+  validate(options?: DataModel.ValidateOptions<Schema>): boolean;
 
   /**
    * Evaluate joint validation rules which apply validation conditions across multiple fields of the model.
@@ -161,15 +179,13 @@ declare abstract class DataModel<
    * This method allows for testing aggregate rules which impose requirements on the overall model.
    * @param data - Candidate data for the model
    * @throws An error if a validation failure is detected
+   * @remarks Other than posting a deprecation warning about and forwarding `data` to `this.prototype._validateModel` if defined,
+   * this is effectively abstract in `DataModel`. Subclasses implementing should type `data` as the `SchemaField.SourceData<>` of
+   * their schema.
    */
+  // TODO(esheyw): dep warning is gone in v13, clean up remarks
   static validateJoint(data: never): void;
 
-  /**
-   * @deprecated since v11; Use the validateJoint static method instead.
-   */
-  // TODO(LukeAbby): Should be SourceType
-  protected _validateModel(data: fields.SchemaField.SourceData<Schema>): void;
-
   /**
    * Update the DataModel locally by applying an object of changes to its source data.
    * The provided changes are cleaned, validated, and stored to the source data object for this model.
@@ -180,76 +196,69 @@ declare abstract class DataModel<
    * @param options - Options which determine how the new data is merged
    * @returns An object containing the changed keys and values
    */
+  // TODO: This should allow dotkeys to be passed
+  // TODO: Without widening changes and the return type, the ActorDelta override is impossible to make correct
+  // changes, options: not null (parameter default only)
   updateSource(
     changes?: fields.SchemaField.UpdateData<Schema>,
-    options?: DataModel.UpdateSourceOptions,
+    options?: DataModel.UpdateOptions,
   ): fields.SchemaField.UpdateData<Schema>;
 
-  /**
-   * Update the source data for a specific DataSchema.
-   * This method assumes that both source and changes are valid objects.
-   * @param schema  - The data schema to update
-   * @param source  - Source data to be updated
-   * @param changes - Changes to apply to the source data
-   * @param options - Options which modify the update workflow
-   * @returns The updated source data
-   * @throws An error if the update operation was unsuccessful
-   */
-  static #updateData(
-    schema: SchemaField.Any,
-    source: object,
-    changes: object,
-    options: DataModel.UpdateOptions,
-  ): object;
-
-  /**
-   * Update the source data for a specific DataField.
-   * @param name    - The field name being updated
-   * @param field   - The field definition being updated
-   * @param source  - The source object being updated
-   * @param value   - The new value for the field
-   * @param options - Options which modify the update workflow
-   * @throws An error if the new candidate value is invalid
-   */
-  static #updateField(
-    name: string,
-    field: DataField.Any,
-    source: object,
-    value: any,
-    options: DataModel.UpdateOptions,
-  ): object;
-
   /**
    * Copy and transform the DataModel into a plain object.
    * Draw the values of the extracted object from the data source (by default) otherwise from its transformed values.
-   * @param source - Draw values from the underlying data source rather than transformed values
-   *                 (default: `true`)
+   * @param source - Draw values from the underlying data source rather than transformed values (default: `true`)
    * @returns The extracted primitive object
    */
-  toObject<Source extends boolean | undefined>(
-    source?: Source,
-  ): Source extends false ? SchemaField.SourceData<Schema> : Readonly<SchemaField.SourceData<Schema>>;
+  toObject(source?: boolean | null): SchemaField.SourceData<Schema>;
 
   /**
    * Extract the source data for the DataModel into a simple object format that can be serialized.
    * @returns The document source data expressed as a plain object
    */
-  toJSON(): fields.SchemaField.SourceData<Schema>;
+  toJSON(): SchemaField.SourceData<Schema>;
 
   /**
    * Create a new instance of this DataModel from a source record.
    * The source is presumed to be trustworthy and is not strictly validated.
    * @param source  - Initial document data which comes from a trusted source.
    * @param context - Model construction context
-   * @remarks Returns `new this()` so needs an override per subclass.
+   * @remarks Returns `new this()` so needs an override per subclass:
+   * ```ts
+   * const mySchema = {
+   *   // etc
+   * }
+   *
+   * type MySchema = typeof mySchema
+   *
+   * // most models likely wont be using this param at all, but its included for completeness
+   * interface MyExtraConstructorOptions {
+   *   someProp: string
+   * }
+   *
+   * class MyDataModel extends DataModel<MySchema, DataModel.Any | null, MyExtraConstructorOptions> {
+   *   static fromSource(
+   *     source: foundry.data.fields.SchemaField.CreateData<MySchema>,
+   *     context?: DataModel.FromSourceOptions<NewParent> & MyExtraConstructorOptions
+   *   ): MyDataModel
+   * }
+   * ```
    */
-  static fromSource(source: never, { strict, ...context }?: DataModel.FromSourceOptions): DataModel.Any;
+  // context: not null (destructured)
+  static fromSource(source: never, context?: DataModel.FromSourceOptions): DataModel.Any;
 
   /**
    * Create a DataModel instance using a provided serialized JSON string.
    * @param json - Serialized document data in string format
    * @returns A constructed data model instance
-   * @remarks Returns `new this()` so needs an override per subclass.
+   * @remarks
+   * Returns `new this()` so needs an override per subclass.
+   *
+   * ```ts
+   * class MyDataModel extends ... {
+   *   static fromJSON(json: string): MyDataModel
+   * }
+   * ```
    */
   static fromJSON(json: string): DataModel.Any;
 
@@ -279,17 +288,28 @@ declare abstract class DataModel<
 }
 
 declare namespace DataModel {
+  interface Any extends AnyDataModel {}
+  interface AnyConstructor extends Identity<typeof AnyDataModel> {}
+
   type CreateData<Schema extends DataSchema> = fields.SchemaField.AssignmentData<Schema> | DataModel<Schema, any>;
 
   type ConstructorDataFor<ConcreteDataModel extends DataModel.Any> = CreateData<SchemaOf<ConcreteDataModel>>;
 
   // TODO(LukeAbby): Make optional only if `{}` is assignable to `AssignmentData`.
-  type ConstructorArgs<Schema extends DataSchema, Parent extends DataModel.Any | null = null> = [
+  type ConstructorArgs<
+    Schema extends DataSchema,
+    Parent extends DataModel.Any | null = null,
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    ExtraConstructorOptions extends AnyObject = {},
+  > = [
+    // not null (parameter default only)
     data?: DataModel.CreateData<Schema>,
 
     // Note(LukeAbby): `{ parent, strict, ...options }`
-    options?: DataModel.DataValidationOptions<Parent>,
+    // not null (destructured)
+    options?: DataModel.ConstructionContext<Parent> & ExtraConstructorOptions,
   ];
+
   /**
    * With the existence of custom module subtypes a system can no longer rely on their configured types being the only ones.
    *
@@ -300,46 +320,6 @@ declare namespace DataModel {
    */
   interface UnknownDataModel extends DataModel<any, any, any> {}
 
-  interface DataValidationOptions<Parent extends Any | null = Any | null> {
-    /**
-     * Throw an error if validation fails.
-     * @defaultValue `true`
-     */
-    strict?: boolean | null | undefined;
-
-    /**
-     * Attempt to replace invalid values with valid defaults?
-     *
-     * @defaultValue `false`
-     */
-    fallback?: boolean | null | undefined;
-
-    /**
-     * Allow partial source data, ignoring absent fields?
-     *
-     * @defaultValue `false`
-     */
-    partial?: boolean | null | undefined;
-
-    /**
-     * If true, invalid embedded documents will emit a warning and be
-     * placed in the invalidDocuments collection rather than causing the
-     * parent to be considered invalid.
-     *
-     * @defaultValue `false`
-     */
-    dropInvalidEmbedded?: boolean | null | undefined;
-
-    /**
-     * A parent DataModel instance to which this DataModel belongs
-     * @defaultValue `null`
-     */
-    parent?: Parent | null | undefined;
-  }
-
-  interface Any extends AnyDataModel {}
-  interface AnyConstructor extends Identity<typeof AnyDataModel> {}
-
   /**
    * A helper type to extract the schema from a {@link DataModel | `DataModel`}.
    * @typeParam ModelType - the DataModel for the embedded data
@@ -356,86 +336,157 @@ declare namespace DataModel {
     ? Fields
     : never;
 
-  interface UpdateOptions {
-    dryRun?: boolean;
-    fallback?: boolean;
-    recursive?: boolean;
-    restoreDelta?: boolean;
-    _collections: Record<string, unknown>;
-    _singletons: Record<string, unknown>;
-    _diff: Record<string, unknown>;
-    _backup: Record<string, unknown>;
+  /** @internal this is how 13.339 splits up the interfaces */
+  type _ConstructionContext = Pick<ValidateOptions<DataSchema>, "strict" | "fallback" | "dropInvalidEmbedded">;
+
+  interface ConstructionContext<Parent extends Any | null = Any | null> extends _ConstructionContext {
+    /**
+     * A parent DataModel instance to which this DataModel belongs
+     * @defaultValue `null`
+     */
+    parent?: Parent | undefined;
   }
 
-  interface FromSourceOptions extends DataModel.DataValidationOptions {
+  interface CloneContext extends _ConstructionContext {
     /**
-     * Models created from trusted source data are validated non-strictly
-     * @defaultValue `false`
+     * A parent DataModel instance to which this DataModel belongs
+     * @defaultValue `this.parent`
+     * @remarks The above default is only applied if this parameter is omitted entirely. Passing `parent: undefined` will
+     * cause the returned DataModel's `parent` (*at runtime*) to be `null`, because it will override the spread-object
+     * default of `this.parent`, and then the parameter default in `new DataModel()` (`null`) will apply.
+     *
+     * **NOTE:** At the type level, the returned model will necessarily have the same parent as the instance `#clone()` is being called
+     * on; Accurate typing of `#parent` requires a cast.
      */
-    strict?: boolean;
+    parent?: Any | null | undefined;
   }
 
-  interface ShimDataOptions {
+  /**
+   * @internal
+   * Updated to 13.339 wording, still accurate for v12
+   */
+  type _ValidateOptions<Schema extends DataSchema> = NullishProps<{
     /**
-     * Apply shims to embedded models?
+     * Validate each individual field?
      * @defaultValue `true`
      */
-    embedded?: boolean;
-  }
+    fields: boolean;
+
+    /**
+     * Perform joint validation on the full data model?
+     * Joint validation will be performed by default if no changes are passed.
+     * Joint validation will be disabled by default if changes are passed.
+     * Joint validation can be performed on a complete set of changes (for example, testing a complete data model) by explicitly passing true.
+     * @remarks If nullish, defaults to `!changes`
+     */
+    joint: boolean;
 
-  interface ValidateOptions<Schema extends DataSchema> {
     /**
      * A specific set of proposed changes to validate, rather than the full source data of the model.
+     * @remarks If not passed or nullish, `validate` will operate on `this._source` instead
      */
-    changes?: fields.SchemaField.AssignmentData<Schema>;
+    changes: fields.SchemaField.AssignmentData<Schema>;
 
     /**
      * If changes are provided, attempt to clean the changes before validating them?
      * @defaultValue `false`
+     * @remarks Only has any effect if a `changes` has been passed with it
+     */
+    clean: boolean;
+
+    /**
+     * Throw an error if validation fails.
+     * @defaultValue `true`
      */
-    clean?: boolean;
+    strict: boolean;
 
     /**
-     * Allow replacement of invalid values with valid defaults?
+     * Allow replacement of invalid values with valid defaults? This option mutates the provided changes.
      * @defaultValue `false`
+     * @see {@link DataField.ValidateOptions.fallback | `DataField.DataValidationOptions.fallback`}
      */
-    fallback?: boolean;
+    fallback: boolean;
+
+    // Foundry describes a `partial` property here, but nothing in DataModel actually *takes* such; `#validate`
+    // generates a value for `partial` from the state of `changes` and `joint` before passing it on to either
+    // `DataModel.cleanData` or `SchemaField#validate`, both of which do have uses for that property downstream
+    // (in `SchemaField#_cleanType` and `#_validateType`). This is a documentation error in v12, fixed in v13.
 
     /**
-     * If true, invalid embedded documents will emit a warning and
-     * be placed in the invalidDocuments collection rather than
-     * causing the parent to be considered invalid.
+     * If true, invalid embedded documents will emit a warning and be placed in the invalidDocuments collection rather
+     * than causing the parent to be considered invalid. This option mutates the provided changes.
      * @defaultValue `false`
+     * @see {@link DataField.ValidateOptions.dropInvalidEmbedded | `DataField.DataValidationOptions.dropInvalidEmbedded`}
      */
     dropInvalidEmbedded: boolean;
+  }>;
+
+  interface ValidateOptions<Schema extends DataSchema> extends _ValidateOptions<Schema> {}
+
+  /**
+   * @deprecated Use {@link DataModel.ConstructionContext | `DataModel.ConstructionContext`} for `new`/`#clone()`/`.create()`,
+   * {@link DataModel.ValidateOptions | `DataModel.ValidateOptions`} for `#validate()`
+   */
+  interface DataValidationOptions<Parent extends Any | null = Any | null> extends ConstructionContext<Parent> {}
+
+  /** `DataModel#constructor` pulls `parent` out of the passed `ConstructionContext` before forwarding to `#_initializeSource` */
+  interface InitializeSourceOptions extends _ConstructionContext {}
+
+  /** `DataModel#constructor` pulls `parent` and `strict` out of the passed `ConstructionContext` before forwarding to `#_configure` */
+  interface ConfigureOptions extends Omit<_ConstructionContext, "strict"> {}
+
+  /** `DataModel#constructor` pulls `parent` out of the passed `ConstructionContext` before forwarding to `#_initialize` */
+  interface InitializeOptions extends _ConstructionContext {}
+
+  type _UpdateOptions = NullishProps<{
+    /** Do not finally apply the change, but instead simulate the update workflow  */
+    dryRun: boolean;
 
     /**
-     * Throw if an invalid value is encountered, otherwise log a warning?
-     * @defaultValue `true`
+     * Allow automatic fallback to a valid initial value if the value provided for a field
+     * in the model is invalid.
      */
-    strict?: boolean;
+    fallback: boolean;
+
+    /** Apply changes to inner objects recursively rather than replacing the top-level object */
+    recursive: boolean;
+
+    /** An advanced option used specifically and internally by the ActorDelta model */
+    restoreDelta: boolean;
+  }>;
 
+  interface UpdateOptions extends _UpdateOptions {}
+
+  /**
+   * @internal
+   * Only necessary to change the default value of `strict`
+   */
+  type _FromSourceOptions = NullishProps<{
     /**
-     * Perform validation on individual fields?
-     * @defaultValue `true`
+     * Models created from trusted source data are validated non-strictly
+     * @defaultValue `false`
+     * @remarks The property description is describing why the default is `false` here,
+     * rather than `true` in normal construction
      */
-    fields?: boolean;
+    strict: boolean;
+  }>;
+
+  /**
+   * @remarks `.fromSource` could take and pass on a specific `Parent`, but this causes
+   * inheritance issues and complicates subclass overriding
+   */
+  interface FromSourceOptions extends ConstructionContext {}
 
+  /** @internal */
+  type _ShimDataOptions = NullishProps<{
     /**
-     * Perform joint validation on the full data model?
-     * Joint validation will be performed by default if no changes are passed.
-     * Joint validation will be disabled by default if changes are passed.
-     * Joint validation can be performed on a complete set of changes (for
-     * example testing a complete data model) by explicitly passing true.
+     * Apply shims to embedded models?
+     * @defaultValue `true`
      */
-    joint?: boolean;
-  }
+    embedded: boolean;
+  }>;
 
-  interface UpdateSourceOptions {
-    dryRun?: boolean;
-    fallback?: boolean;
-    recursive?: boolean;
-  }
+  interface ShimDataOptions extends _ShimDataOptions {}
 }
 
 // This uses `any` because `Schema` and `Parent` are invariant