@league-of-foundry-developers/foundry-vtt-types 13.346.0-beta.20250705112003 → 13.346.0-beta.20250705133313

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

@@ -1193,6 +1193,40 @@ declare namespace Document {
       // TODO: Handle as part of the UUID update.
       uuid?: string;
     }
+
+    // Like `keyof` but handles properties desirable for flags:
+    // - `never` returns `never` (instead of `PropertyKey`).
+    // - `unknown` returns `string` (instead of `never`).
+    // - Allows any key in a union of objects (instead of just the common keys).
+    // - Strips out non string keys.
+    type FlagKeyOf<T> = unknown extends T
+      ? string
+      : [T] extends [never]
+        ? never
+        : T extends unknown
+          ? // Note(LukeAbby): This is a quick hack to get core flags on all documents.
+            // This should definitely be improved.
+            keyof (T & CoreFlags) & string
+          : never;
+
+    type FlagGetKey<T, K extends PropertyKey> = T extends unknown
+      ? K extends keyof (T & CoreFlags)
+        ? (T & CoreFlags)[K]
+        : never
+      : never;
+
+    // Note(LukeAbby): It's at times been very important for `GetFlag` to be covariant over `ConcreteSchema`.
+    // If it isn't then issues arise where the `Document` type ends up becoming invariant.
+    // Currently it is actually contravariant over `ConcreteSchema` and this may cause issues (because of the usage of `keyof`).
+    // Unfortunately it's not easy to avoid because the typical `GetKey` trick has issues between `never`, not defined at all, and `unknown` etc.
+    type GetFlag<Flags extends object, S extends string, K extends string> = FlagGetKey<
+      FlagGetKey<Flags & CoreFlags, S>,
+      K
+    >;
+
+    // The type `{}` is useful here because in an intersection it reduces down to nothing unlike `EmptyObject`.
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    type ConfiguredFlagsForName<Name extends Type> = GetKey<FlagConfig, Name, {}>;
   }
 
   /** Any Document, that is a child of the given parent Document. */
@@ -1322,11 +1356,6 @@ declare namespace Document {
     NameFor<ConcreteDocument>
   >;
 
-  type TemporaryIf<D extends Document.Any, Temporary extends boolean | undefined> = Temporary extends true
-    ? D
-    : // eslint-disable-next-line @typescript-eslint/no-deprecated
-      Stored<D>;
-
   type StoredForName<DocumentType extends Document.Type> =
     | (DocumentType extends "ActiveEffect" ? ActiveEffect.Stored : never)
     | (DocumentType extends "ActorDelta" ? ActorDelta.Stored : never)
@@ -1411,10 +1440,6 @@ declare namespace Document {
 
   type ConfiguredSourceForName<Name extends Type> = GetKey<SourceConfig, Name, EmptyObject>;
 
-  // The type `{}` is useful here because in an intersection it reduces down to nothing unlike `EmptyObject`.
-  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
-  type ConfiguredFlagsForName<Name extends Type> = GetKey<FlagConfig, Name, {}>;
-
   type SchemaFor<ConcreteDocument extends Internal.Instance.Any> =
     ConcreteDocument extends Internal.Instance<infer _1, infer Schema, infer _2> ? Schema : never;
 
@@ -1426,44 +1451,6 @@ declare namespace Document {
       : never;
   };
 
-  type Flags<ConcreteDocument extends Internal.Instance.Any> = OptionsForSchema<SchemaFor<ConcreteDocument>>;
-
-  /** @internal */
-  interface OptionsInFlags<Options extends DataField.Options.Any> {
-    readonly flags?: DataField<Options, any>;
-  }
-
-  // These types only exists to simplify solving the `Document` type. Using `Document.Flags<this>` means the constraint `this extends Document.Any` has to be proved.
-  // This is much more complex than proving the constraint for `Document.FlagsInternal<Schema>` that `Schema extends DataSchema`.
-
-  // TODO: This needs to use the derived flags not just how they're initialized.
-  type OptionsForSchema<Schema extends DataSchema> =
-    RemoveIndexSignatures<Schema> extends OptionsInFlags<infer Options> ? DataField.InitializedType<Options> : never;
-
-  // Like `keyof` but handles properties desirable for flags:
-  // - `never` returns `never` (instead of `PropertyKey`).
-  // - `unknown` returns `string` (instead of `never`).
-  // - Allows any key in a union of objects (instead of just the common keys).
-  // - Strips out non string keys.
-  type FlagKeyOf<T> = unknown extends T
-    ? string
-    : [T] extends [never]
-      ? never
-      : T extends unknown
-        ? keyof T & string
-        : never;
-
-  type FlagGetKey<T, K extends PropertyKey> = T extends unknown ? (K extends keyof T ? T[K] : never) : never;
-
-  // Note(LukeAbby): It's at times been very important for `GetFlag` to be covariant over `ConcreteSchema`.
-  // If it isn't then issues arise where the `Document` type ends up becoming invariant.
-  // Currently it is actually contravariant over `ConcreteSchema` and this may cause issues (because of the usage of `keyof`).
-  // Unfortunately it's not easy to avoid because the typical `GetKey` trick has issues between `never`, not defined at all, and `unknown` etc.
-  type GetFlag<Name extends Document.Type, S extends string, K extends string> = FlagGetKey<
-    FlagGetKey<Document.ConfiguredFlagsForName<Name>, S>,
-    K
-  >;
-
   interface CoreFlags {
     core?: {
       sheetLock?: boolean;
@@ -2416,13 +2403,13 @@ declare namespace Document {
 
   namespace DropData {
     /**
-     * @deprecated - This type is likely too broad to be useful. Deprecated without replacement.
+     * @deprecated This type is likely too broad to be useful. Deprecated without replacement.
      */
     // eslint-disable-next-line @typescript-eslint/no-deprecated
     type Any = DropData<any>;
 
     /**
-     * @deprecated - This type is a part of the drop data which is now gotten through
+     * @deprecated This type is a part of the drop data which is now gotten through
      * `[Document].DropData`. Use that instead.
      */
     interface Data<T extends Document.Any> {
@@ -2431,7 +2418,7 @@ declare namespace Document {
     }
 
     /**
-     * @deprecated - This type is a part of the drop data which is now gotten through
+     * @deprecated This type is a part of the drop data which is now gotten through
      * `[Document].DropData`. Use that instead.
      */
     interface UUID {
@@ -2451,4 +2438,65 @@ declare namespace Document {
     data?: CreateData,
     context?: Document.ConstructionContext<Parent>,
   ];
+
+  /**
+   * @deprecated This type has been moved to be internal. If you have a need for this type please
+   * let us know.
+   */
+  type ConfiguredFlagsForName<Name extends Type> = Internal.ConfiguredFlagsForName<Name>;
+
+  /**
+   * @deprecated This type is no longer used and will be removed.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-deprecated
+  type Flags<ConcreteDocument extends Internal.Instance.Any> = OptionsForSchema<SchemaFor<ConcreteDocument>>;
+
+  /**
+   * @internal
+   * @deprecated This type is no longer used and will be removed.
+   */
+  interface OptionsInFlags<Options extends DataField.Options.Any> {
+    readonly flags?: DataField<Options, any>;
+  }
+
+  // These types only exists to simplify solving the `Document` type. Using `Document.Flags<this>` means the constraint `this extends Document.Any` has to be proved.
+  // This is much more complex than proving the constraint for `Document.FlagsInternal<Schema>` that `Schema extends DataSchema`.
+
+  /**
+   * @deprecated This type is being made internal.
+   */
+  type OptionsForSchema<Schema extends DataSchema> =
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    RemoveIndexSignatures<Schema> extends OptionsInFlags<infer Options> ? DataField.InitializedType<Options> : never;
+
+  /**
+   * @deprecated `FlagKeyOf` is being made internal. If you need this for some reason please let
+   * us know.
+   */
+  type FlagKeyOf<T> = Internal.FlagKeyOf<T>;
+
+  /**
+   * @deprecated `FlagGetKey` is being made internal. If you need this for some reason please let
+   * us know.
+   */
+  type FlagGetKey<T, K extends PropertyKey> = Internal.FlagGetKey<T, K>;
+
+  /**
+   * @deprecated `GetFlag` has been moved to be internal. Use `[Document].Flag.Get` instead.
+   * If you need this for some reason please let us know.
+   */
+  type GetFlag<Name extends Document.Type, S extends string, K extends string> = Internal.GetFlag<
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    Extract<Document.ConfiguredFlagsForName<Name>, object>,
+    S,
+    K
+  >;
+
+  /**
+   * @deprecated Use the `TemporaryIf` available on each sub-document.
+   */
+  type TemporaryIf<D extends Document.Any, Temporary extends boolean | undefined> = Temporary extends true
+    ? D
+    : // eslint-disable-next-line @typescript-eslint/no-deprecated
+      Stored<D>;
 }

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

@@ -55,20 +55,37 @@ type UnmergePartial<
   [K in keyof Initialized as K extends keyof BaseData ? never : K]: Initialized[K];
 };
 
-type MergePartial<BaseData, DerivedData> = {
+type MergePartial<BaseThis, BaseData, DerivedData> = {
+  [K in keyof BaseThis as K extends keyof BaseData | keyof DerivedData ? never : K]: BaseThis[K];
+} & {
   [K in keyof BaseData as K extends keyof DerivedData ? never : K]: BaseData[K];
 } & {
-  [K in keyof DerivedData as K extends PartialKey<BaseData, DerivedData> ? K : never]?: K extends keyof BaseData
-    ? _MergePartial<BaseData[K], DerivedData[K]>
-    : DerivedData[K];
+  [K in keyof DerivedData as K extends PartialKey<BaseData, DerivedData> ? K : never]?: _MergePartial<
+    K,
+    BaseThis,
+    BaseData,
+    DerivedData[K]
+  >;
 } & {
-  [K in keyof DerivedData as K extends PartialKey<BaseData, DerivedData> ? never : K]: K extends keyof BaseData
-    ? _MergePartial<BaseData[K], DerivedData[K]>
-    : DerivedData[K];
+  [K in keyof DerivedData as K extends PartialKey<BaseData, DerivedData> ? never : K]: _MergePartial<
+    K,
+    BaseThis,
+    BaseData,
+    DerivedData[K]
+  >;
 };
 
 // TODO(LukeAbby): The logic here is over-simplified.
-type _MergePartial<Base, Derived> = [Base, Derived] extends [object, object] ? MergePartial<Base, Derived> : Derived;
+type _MergePartial<K extends PropertyKey, BaseThis, BaseData, Derived> =
+  IsObject<Derived> extends true ? MergePartial<GetObject<BaseThis, K>, GetObject<BaseData, K>, Derived> : Derived;
+
+type GetObject<T, K extends PropertyKey> = T extends { readonly [_ in K]?: infer Result }
+  ? IsObject<Result> extends true
+    ? Result
+    : // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+      {}
+  : // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    {};
 
 type PartialKey<BaseData, DerivedData> = {
   [K in keyof MetadataFor<DerivedData>]: _PartialKey<K, GetKey<MetadataFor<BaseData>, K>, MetadataFor<DerivedData>[K]>;
@@ -162,8 +179,16 @@ declare namespace TypeDataModel {
       : never;
 
   type PrepareDerivedDataThis<BaseThis extends Internal.Instance.Any> =
-    BaseThis extends Internal.Instance<infer _1, infer _2, infer _3, infer BaseData, infer DerivedData>
-      ? Override<BaseThis, MergePartial<RemoveIndexSignatures<BaseData>, RemoveIndexSignatures<DerivedData>>>
+    BaseThis extends Internal.Instance<infer Schema, infer _1, infer _2, infer BaseData, infer DerivedData>
+      ? Override<
+          BaseThis,
+          MergePartial<
+            // TODO: Put back in `BaseThis` and write as yet another unmerge
+            SchemaField.InitializedData<Schema>,
+            RemoveIndexSignatures<BaseData>,
+            RemoveIndexSignatures<DerivedData>
+          >
+        >
       : never;
 
   type ParentAssignmentType<Schema extends DataSchema, Parent extends Document.Internal.Instance.Any> = SimpleMerge<

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

@@ -731,7 +731,7 @@ declare class PrototypeToken extends DataModel<PrototypeToken.Schema, PrototypeT
   getFlag<Scope extends TokenDocument.Flags.Scope, Key extends TokenDocument.Flags.Key<Scope>>(
     scope: Scope,
     key: Key,
-  ): Document.GetFlag<TokenDocument.Name, Scope, Key>;
+  ): TokenDocument.Flags.Get<Scope, Key>;
 
   /**
    * @see {@link foundry.abstract.Document.setFlag | `foundry.abstract.Document#setFlag`}
@@ -739,7 +739,7 @@ declare class PrototypeToken extends DataModel<PrototypeToken.Schema, PrototypeT
   setFlag<
     Scope extends TokenDocument.Flags.Scope,
     Key extends TokenDocument.Flags.Key<Scope>,
-    Value extends Document.GetFlag<TokenDocument.Name, Scope, Key>,
+    Value extends TokenDocument.Flags.Get<Scope, Key>,
   >(scope: Scope, key: Key, value: Value): Promise<this>;
 
   /**