@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.345.1-beta.20250704.94554

package/src/utils/index.d.mts

@@ -1,12 +1,17 @@
 import type { Document } from "../foundry/common/abstract/_module.d.mts";
 
-type ConfiguredModuleData<Name extends string> = Name extends keyof ModuleConfig ? ModuleConfig[Name] : EmptyObject;
+export {};
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+type ConfiguredModuleData<Name extends string> = Name extends keyof ModuleConfig ? ModuleConfig[Name] : {};
 
 /**
  * This type exists due to https://github.com/microsoft/TypeScript/issues/55667
  * This will be deprecated once this issue is solved.
  */
-export type FixedInstanceType<T extends AnyConstructor> = T extends abstract new (...args: infer _) => infer R
+export type FixedInstanceType<T extends abstract new (...args: never) => any> = T extends abstract new (
+  ...args: infer _
+) => infer R
   ? R
   : never;
 
@@ -24,16 +29,26 @@ export type LoggingLevels = "debug" | "log" | "info" | "warn" | "error";
 /**
  * `GetKey` accesses a property while intentionally ignoring index signatures. This means `GetKey<Record<string, unknown>, "foo">` will return `never`.
  */
-// Note(LukeAbby): There are two tricky cases:
-// - `T = {}` would regularly always return `unknown`. The fix here adding a single dummy property `{ _?: any } & T`.
-// - `T = never` would regularly always return `unknown`. The fix here is adding `_GetKey` which makes the type distributive and therefore `never` as an input becomes `never` in the output.
-export type GetKey<T, K extends PropertyKey, D = never> = _GetKey<{ _?: any } & T, K, D>;
-
-type _GetKey<T, K extends PropertyKey, D> = T extends { readonly [_ in K]?: infer V } ? V : D;
+// Note(LukeAbby): There are five tricky cases:
+// - `T = {}` and `T = object` could easily return `unknown` and must be excluded.
+// - `T = never` might either distribute out or return `unknown`. The fix here is checking if `any` is assignable to it.
+// - `T = { prop?: U }` with `exactOptionalPropertyTypes` should return `U | undefined` not `U`.
+// - `T` has getters `GetKey` should still access it, this means checking `keyof T` is not helpful.
+export type GetKey<T, K extends PropertyKey, D = never> = [object] extends [T] // Handle `{}` and `object`
+  ? D
+  : [any] extends [T] // Handle never
+    ? _GetKey<T, K, D>
+    : D;
+
+// Note(LukeAbby): This uses `infer _V` specifically to avoid index signatures.
+// However it isn't `T extends { readonly [_ in K]?: infer V } ? V : D` as under
+// `exactOptionalPropertyTypes` this would not include `undefined` whereas `T[K]` does.
+type _GetKey<T, K extends PropertyKey, D> = T extends { readonly [_ in K]?: infer _V } ? T[K] : D;
 
 /**
  * `Partial` is usually the wrong type.
  * In order to make it easier to audit unintentional uses of `Partial` this type is provided.
+ * Also allows specifying certain keys to make partial.
  *
  * ### Picking the right helper type
  * - Favor `NullishProps` whenever it is valid. Allowing both `null` and
@@ -47,7 +62,7 @@ type _GetKey<T, K extends PropertyKey, D> = T extends { readonly [_ in K]?: infe
  *   `Object.assign({}, defaultOptions, options)`,
  *   `foundry.utils.mergeObject(defaultOptions, options)`, or so on.
  *
- *   Note that {@link foundry.utils.mergeObject | `foundry.utils.mergeObject`}
+ *   Note that {@linkcode foundry.utils.mergeObject}
  *   also expands the object. So once `ExpandsTo` exists you should also use
  *   that helper type.
  *
@@ -61,7 +76,7 @@ type _GetKey<T, K extends PropertyKey, D> = T extends { readonly [_ in K]?: infe
  *   The most common time this shows up is with the pattern
  *   `exampleFunction({ prop = "foo" } = {}) { ... }`.
  */
-export type IntentionalPartial<T> = Partial<T>;
+export type IntentionalPartial<T extends object> = Partial<T>;
 
 /**
  * This type is used to make a constraint where `T` must be statically known to overlap with `U`.
@@ -93,7 +108,7 @@ export type OverlapsWith<T, U> = [Extract<T, U>, any] extends [U, Extract<T, U>]
  * This is safer than what `OverlapsWith` provides as it ensures that if the type is an array it is an array of `Item`.
  * Assumes readonly arrays are permitted.
  *
- * Note that `never[]` and `any[]` are still accepted due to the unsoundness of those types.
+ * Note that `never[]` and `any[]` are still accepted due to the fundamental nature of these types.
  *
  * @example
  * ```ts
@@ -118,8 +133,8 @@ export type OverlapsWith<T, U> = [Extract<T, U>, any] extends [U, Extract<T, U>]
  * takesNumericArray(Math.random() > 0.5 ? [1, 2, 3] : ["foo", "bar"]); // Error, at runtime it could be an array of the wrong type and that isn't handled. Notably this would succeed with `OverlapsWith`.
  * ```
  */
-export type ArrayOverlaps<T, Item> =
-  Extract<T, readonly unknown[]> extends readonly Item[] ? OverlapsWith<T, readonly Item[]> : readonly Item[];
+export type ArrayOverlaps<Arr, T> =
+  Extract<Arr, readonly unknown[]> extends readonly T[] ? OverlapsWith<Arr, readonly T[]> : readonly T[];
 
 /**
  * Use this whenever a type is given that should match some constraint but is
@@ -250,34 +265,16 @@ export type ConformRecord<T extends object, V, D extends V = V> = {
  * this behavior is disabled for functions in most codebases (including this one)
  * because of the `strictFunctionTypes` compiler flag, implicit under `strict: true`.
  * See: https://github.com/Microsoft/TypeScript/wiki/FAQ#why-are-function-parameters-bivariant
+ *
+ * Note that this does not work well with exotic functions. Unexpected behavior may occur with:
+ * - Overloaded functions.
+ * - Functions with additional properties, e.g. `(() => number) & { prop: string }`.
+ * - Functions of the shape `(...args: never[]) => T`.
  */
 export type ToMethod<T extends AnyFunction> = {
   method(...args: Parameters<T>): ReturnType<T>;
 }["method"];
 
-export type ConfiguredSheetClass<T extends Document.AnyConstructor> = GetKey<
-  GetKey<CONFIG, T["metadata"]["name"]>,
-  "sheetClass",
-  T
->;
-
-export type ObjectClass<T extends Document.AnyConstructor> = GetKey<
-  GetKey<CONFIG, T["metadata"]["name"]>,
-  "objectClass",
-  T
->;
-
-export type LayerClass<T extends Document.AnyConstructor> = GetKey<
-  GetKey<CONFIG, T["metadata"]["name"]>,
-  "layerClass",
-  T
->;
-
-/**
- * Actual document types that go in folders
- */
-export type FolderDocumentTypes = Exclude<foundry.CONST.FOLDER_DOCUMENT_TYPES, "Compendium">;
-
 export type MaybeEmpty<T extends AnyObject> =
   | T
   | {
@@ -288,9 +285,11 @@ export type MaybeEmpty<T extends AnyObject> =
  * The following uses `extends object` instead of `AnyObject` to allow `O = typeof SomeClass`
  */
 export type PropertiesOfType<O extends object, T> = {
-  [K in keyof O]: [O[K], T] extends [T, O[K]] ? K : never;
+  [K in keyof O]: _KeyOfType<O[K], K, T>;
 }[keyof O];
 
+type _KeyOfType<V, K, T> = V extends T ? K : never;
+
 declare class Branded<in out BrandName extends string> {
   #brand: BrandName;
 }
@@ -375,33 +374,23 @@ export type Brand<BaseType, BrandName extends string> = BaseType & Branded<Brand
  * //   ^ { x: string, y: number }
  *
  * function example<T extends { someProp: number } | { anotherProp: string }>(t: T) {
- *   Object.assign(t, { a: "foo" }, {b: 2}) satisfies ObjectIntersection
- *   Object.assign(t, { a: "foo" }, {b: 2}) satisfies PrettyObjectIntersection
- *   //                                     ^ Type 'T & { a: string; } & { b: number; }' does not satisfy the expected type '{ a: string; b: number; }'.
+ *   Object.assign(t, { a: "foo" }, { b: 2 }) satisfies ObjectIntersection
+ *   Object.assign(t, { a: "foo" }, { b: 2 }) satisfies PrettyObjectIntersection
+ *   //                                       ^ Type 'T & { a: string; } & { b: number; }' does not satisfy the expected type '{ a: string; b: number; }'.
  *   // This is an example of changing type behavior. The first line is allowed but the second errors.
  *   // This type of situation will realistically never come up in real code because it's so contrived.
- *   // Note that this difference only appears when generic, specifically `T extends Object | NonObject`.
+ *   // Note that this difference only appears when generic, specifically `T extends SomeConcreteObject | U`.
  *   // See https://github.com/microsoft/TypeScript/pull/60726 for some context.
  * }
  * ```
  */
-export type PrettifyType<T> = T extends AnyObject
+// Note(LukeAbby): This uses `AnyObject` as a constraint rather than in the body due to this circularity: https://tsplay.dev/NDpRRN
+export type PrettifyType<T extends AnyObject> = T extends unknown
   ? {
       [K in keyof T]: T[K];
-    }
-  : // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
-    T & unknown;
-
-/**
- * This behaves the same as {@link PrettifyType | `PrettifyType`} except instead
- * of prettifying only the first level it prettifies all levels of an object. of prettifying only the first level it prettifies all levels of an object.
- */
-export type PrettifyTypeDeep<T> = T extends AnyObject
-  ? {
-      [K in keyof T]: PrettifyTypeDeep<T[K]>;
-    }
-  : // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
-    T & unknown;
+      // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+    } & unknown
+  : never;
 
 /**
  * Convert a union of the form `T1 | T2 | T3 | ...` into an intersection of the form `T1 & T2 & T3 & ...`.
@@ -499,12 +488,15 @@ export type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : nev
  */
 // Allowing passing any `object` is done because it's more convenient for the end user.
 // Note that `{}` should always be assignable to `DeepPartial<T>`.
-export type DeepPartial<T extends object> = {
-  [K in keyof T]?: _DeepPartial<T[K]>;
-};
+export type DeepPartial<T extends object> = _DeepPartial<T>;
 
-// This type has to be factored out for distributivity.
-type _DeepPartial<T> = T extends object ? (T extends AnyArray | AnyFunction | AnyConstructor ? T : DeepPartial<T>) : T;
+type _DeepPartial<T> = T extends object
+  ? T extends AnyArray | AnyFunction | AnyConstructor
+    ? T
+    : {
+        [K in keyof T]?: _DeepPartial<T[K]>;
+      }
+  : T;
 
 /**
  * Gets all possible keys of `T`. This is useful because if `T` is a union type
@@ -527,7 +519,7 @@ export type AllKeysOf<T extends object> = T extends unknown ? keyof T : never;
  *   `Object.assign({}, defaultOptions, options)`,
  *   `foundry.utils.mergeObject(defaultOptions, options)`, or so on.
  *
- *   Note that {@link foundry.utils.mergeObject | `foundry.utils.mergeObject`}
+ *   Note that {@linkcode foundry.utils.mergeObject}
  *   also expands the object. So once `ExpandsTo` exists you should also use
  *   that helper type.
  *
@@ -543,11 +535,8 @@ export type AllKeysOf<T extends object> = T extends unknown ? keyof T : never;
  *
  * @internal
  */
-export type InexactPartial<T extends object, K extends AllKeysOf<T> = AllKeysOf<T>> = {
-  [K2 in keyof T as Extract<K2, K>]?: T[K2] | undefined;
-} & {
-  // Note(LukeAbby): This effectively inlines `Omit<T, K>`, hoping for slightly better type display.
-  [K2 in keyof T as Exclude<K2, K>]: T[K2];
+export type InexactPartial<T extends object> = {
+  [K in keyof T]?: T[K] | undefined;
 };
 
 /**
@@ -566,7 +555,7 @@ export type InexactPartial<T extends object, K extends AllKeysOf<T> = AllKeysOf<
  *   `Object.assign({}, defaultOptions, options)`,
  *   `foundry.utils.mergeObject(defaultOptions, options)`, or so on.
  *
- *   Note that {@link foundry.utils.mergeObject | `foundry.utils.mergeObject`}
+ *   Note that {@linkcode foundry.utils.mergeObject}
  *   also expands the object. So once `ExpandsTo` exists you should also use
  *   that helper type.
  *
@@ -582,11 +571,8 @@ export type InexactPartial<T extends object, K extends AllKeysOf<T> = AllKeysOf<
  *
  * @internal
  */
-export type NullishProps<T extends object, K extends AllKeysOf<T> = AllKeysOf<T>> = {
-  [K2 in keyof T as Extract<K2, K>]?: T[K2] | null | undefined;
-} & {
-  // Note(LukeAbby): This effectively inlines `Omit<T, K>`, hoping for slightly better type display.
-  [K2 in keyof T as Exclude<K2, K>]: T[K2];
+export type NullishProps<T extends object> = {
+  [K in keyof T]?: T[K] | null | undefined;
 };
 
 /**
@@ -605,7 +591,7 @@ export type Expanded<O> = O extends AnyObject
  * Union type of the types of the values in `T`
  * @internal
  */
-export type ValueOf<T> = T extends ReadonlyArray<infer V> ? V : T[keyof T];
+export type ValueOf<T extends object> = T extends ReadonlyArray<infer V> ? V : T[keyof T];
 
 type OmitIndex<K extends PropertyKey> = string extends K
   ? never
@@ -618,7 +604,7 @@ type OmitIndex<K extends PropertyKey> = string extends K
 /**
  * Gets the keys of `T` but excluding index signatures unlike `keyof T`. For example `Record<string, any> & { foo: number }` will produce `string` with `keyof` but `foo` with `ConcreteKeys`.
  */
-export type ConcreteKeys<T> = T extends never
+export type ConcreteKeys<T> = [T] extends [never]
   ? never
   : keyof {
       [K in keyof T as OmitIndex<K>]: never;
@@ -629,7 +615,7 @@ export type ConcreteKeys<T> = T extends never
  */
 // NOTE(LukeAbby): It may seem easier to write `Pick<T, ConcreteKeys<T>>` but this stops it from being a homomorphic mapped type and regresses its power when given a generic type parameter or `this`.
 // See: https://www.typescriptlang.org/play/?#code/KYDwDg9gTgLgBDAnmYcDCEB2BjKwbADSwiAzgDwAqAfHALxwDWJEAZnAN4BQccA2oTgBLTExbtKcAIak4pGFBEBzOKAKYAJrMEB+OJmAA3YFDgAufQFcAtgCMTqkOq1xd+ow4ulEdiABtHZ204PQNjUwtCAF0LMJMAbi4AX0SuJBQ4ACVgawhjAElNUABlISVMKRhLPAoaejgABSFsRioAGnQsXHwiElrqalTsPxlZABFKqQBZCA1gP3Ji7AALHKlabl454ak8OFy5vwts3IKikFLyyurgCiXV63Xkri4d0lliy1sZw8WVtcCwE0sg4cCUQJMzQaUAgYAsUkwiHi-EIXgUyhiVjsDiStDUQJcExg01m8z+D3WnB4+3wy1mAAoAJRU3i8AD0bLglGWQlkYBhKCgiDkdMsfg0jl58FslngGggt0wAHIYAA6am8GA80iqg7zVXggyKbDQ2GpVkIbW60l+VVSWzYRK8JLJIA
-export type RemoveIndexSignatures<T extends AnyObject> = {
+export type RemoveIndexSignatures<T extends object> = {
   [K in keyof T as OmitIndex<K>]: T[K];
 };
 
@@ -648,23 +634,59 @@ export type Titlecase<S extends string> = S extends `${infer A} ${infer B}`
  * Nested properties of type `object` are merged recursively unless the property
  * in `U` is an `Array`.
  *
- * @typeParam T - The base type that `U` will be merged into.
- * @typeParam U - The type that will be merged into `T`.
+ * @template T - The base type that `U` will be merged into.
+ * @template U - The type that will be merged into `T`.
+ */
+export type Merge<T, U> = U extends object ? (T extends object ? _Merge<T, U> : U) : U;
+
+type _Merge<T extends object, U extends object> = T extends AnyArray
+  ? U extends AnyArray
+    ? MergeArray<T, U>
+    : _MergeObject<T, U>
+  : _MergeObject<T, U>;
+
+type _MergeObject<T extends object, U extends object> = U extends AnyObject
+  ? T extends AnyObject
+    ? _MergePlainObject<T, U>
+    : _MergeComplexObject<T, U>
+  : _MergeComplexObject<T, U>;
+
+type MergeArray<T extends AnyArray, U extends AnyArray> = number extends U["length"] | T["length"]
+  ? Array<T[number] | U[number]>
+  : [...U, ...DropFirstN<T, U["length"]>];
+
+type DropFirstN<
+  T extends AnyArray,
+  DropN extends number,
+  Accumulator extends AnyArray = [],
+> = Accumulator["length"] extends DropN
+  ? T
+  : T extends [unknown, ...infer Items]
+    ? DropFirstN<Items, DropN, [...Accumulator, 1]>
+    : [];
+
+// TODO(LukeAbby): This needs to be more complex as to account for stuff like optionality correctly.
+type _MergePlainObject<T extends object, U extends object> = {
+  [K in keyof T as K extends keyof U ? never : K]: T[K];
+} & {
+  [K in keyof U]: T extends { readonly [_ in K]?: infer V } ? Merge<V, U[K]> : U[K];
+};
+
+interface _MergeComplexObject<T extends object, U extends object> extends _Override<T, _MergePlainObject<T, U>> {}
+
+/**
+ * Overrides properties of `T` with properties in `U`. Be careful using this type as its internal
+ * implementation is likely a bit shaky.
+ *
+ * Note: `U` must NOT be a union. If it is unexpected behavior may occur.
  */
-export type Merge<T, U> =
-  IsObject<U> extends true
-    ? IsObject<T> extends true
-      ? SimpleMerge<
-          T,
-          {
-            [K in keyof U]: T extends { readonly [_ in K]?: infer V } ? Merge<V, U[K]> : U[K];
-          }
-        >
-      : U
-    : U;
+export type Override<T extends object, U extends object> = T extends unknown ? _Override<T, U> : never;
+
+// @ts-expect-error - This pattern is inherently an error.
+interface _Override<T extends object, U extends object> extends U, T {}
 
 /**
- * Returns whether the type is a plain object. Excludes functions and arrays while still being friendly to interfaces.
+ * Returns whether the type is a plain object. Excludes functions, arrays, and constructors while still being friendly to interfaces.
  *
  * @example
  * ```ts
@@ -681,16 +703,12 @@ export type Merge<T, U> =
  * type RecordFails = Interface extends Record<string, unknown> ? true : false; // false
  * ```
  */
-export type IsObject<T> = T extends { readonly [K: string]: any }
-  ? T extends AnyArray | AnyFunction
-    ? false
-    : true
-  : false;
+export type IsObject<T> = T extends object ? (T extends AnyArray | AnyFunction | AnyConstructor ? false : true) : false;
 
 /**
  * A simple, non-recursive merge type.
- * @typeParam Target - the target type to merge into
- * @typeParam Override - the type whose properties override the ones in Target
+ * @template Target - the target type to merge into
+ * @template Override - the type whose properties override the ones in Target
  */
 export type SimpleMerge<Target, Override> = Omit<Target, keyof Override> & Override;
 
@@ -729,13 +747,11 @@ export type GetDataReturnType<T extends object> = GetDataConfigOptions<T>[GetDat
  * removes all properties rom an object, because an empty interface was given,
  * or so on.
  *
- * Type params extend `object` instead of `AnyObject` to allow interfaces
- *
  * @example
  * ```ts
  * type ObjectArray<T extends Record<string, unknown>> = T[];
  *
- * // As you would hope a union can't be assigned. It errors with:
+ * // As you would hope a string can't be assigned in a union or not. It errors with:
  * // "type 'string' is not assignable to type 'Record<string, unknown>'."
  * type UnionErrors = ObjectArray<string | { x: number }>;
  *
@@ -752,8 +768,13 @@ export type GetDataReturnType<T extends object> = GetDataConfigOptions<T>[GetDat
  * const emptyObject: EmptyObjectArray = [1, "foo", () => 3];
  * ```
  */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export type HandleEmptyObject<T extends object, D extends object = EmptyObject> = [{}] extends [T] ? D : T;
+export type HandleEmptyObject<O, D = EmptyObject> =
+  // Note(LukeAbby): This uses a strict equality test to differentiate types like `{ onlyOptional?: true }`
+  // and `object` from `{}`. More naive tests like `[{}] extends [O] ? ... : ...` fails these cases
+  // due to particular unsoundness rules around `{}`.
+  //
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  (<T>() => T extends {} ? true : false) extends <T>() => T extends O ? true : false ? D : O;
 
 /**
  * This type allows any plain objects. In other words it disallows functions
@@ -787,7 +808,7 @@ export type AnyMutableObject = {
 /**
  * Use this type to allow any array. This allows readonly arrays which is
  * generally what you want. If you need a mutable array use the
- * {@link MutableArray | `MutableArray`} type instead of the builtin `T[]` or
+ * {@linkcode MutableArray} type instead of the builtin `T[]` or
  * `Array` types. This allows us to be more explicit about intent.
  *
  * Consider being more specific if possible. You should generally try to use a
@@ -802,7 +823,7 @@ export type AnyArray = readonly unknown[];
 /**
  * Use this type to allow a mutable array of type `T`. Only use this if the
  * array can be soundly mutated. Otherwise you should be using
- * `readonly T[]` or {@link ReadonlyArray | `ReadonlyArray`}
+ * `readonly T[]` or {@linkcode ReadonlyArray}
  */
 export type MutableArray<T> = Array<T>;
 
@@ -820,17 +841,14 @@ export type MutableArray<T> = Array<T>;
  * - `(...args: any[]) => any` - If someone explicitly accesses the parameters or uses the return value you get `any` which is not safe.
  * - `(...args: unknown[]) => unknown` - This allows obviously unsound calls like `fn(1, "foo")` because it indicates it can take any arguments.
  */
-// The explicit arg0 does not prevent a function with no arguments from being assigned to `AnyFunction` because any function that takes less arguments can be assigned to one that takes more.
-// The point of this is to prevent it from being possible to call with 0 arguments.
-// never is used to make it impossible to call with anything besides `never` or `any`. This makes it the most type safe way to define any function.
-export type AnyFunction = (arg0: never, ...args: never[]) => unknown;
+export type AnyFunction = (...args: never) => unknown;
 
 /**
  * Use this type to allow any class, abstract class, or class-like constructor.
  *
- * See {@link AnyConcreteConstructor | `AnyConcreteConstructor`} if you cannot
+ * See {@linkcode AnyConcreteConstructor} if you cannot
  * allow abstract classes. Please also consider writing a comment
- * explaining why {@link AnyConcreteConstructor | `AnyConcreteConstructor`} is
+ * explaining why {@linkcode AnyConcreteConstructor} is
  * necessary.
  *
  * @example
@@ -842,7 +860,7 @@ export type AnyFunction = (arg0: never, ...args: never[]) => unknown;
  * const classLike: AnyConstructor = Date;
  * ```
  */
-export type AnyConstructor = abstract new (arg0: never, ...args: never[]) => unknown;
+export type AnyConstructor = abstract new (...args: never) => unknown;
 
 /**
  * Use this type to allow any class or class-like constructor but disallow
@@ -850,7 +868,7 @@ export type AnyConstructor = abstract new (arg0: never, ...args: never[]) => unk
  *
  * Use this type only when abstract classes would be problematic such as the
  * base type of a mixin. Please consider writing a comment explaining why.
- * See {@link AnyConstructor | `AnyConstructor`} to also allow abstract classes.
+ * See {@linkcode AnyConstructor} to also allow abstract classes.
  *
  * @example
  * ```ts
@@ -863,31 +881,31 @@ export type AnyConstructor = abstract new (arg0: never, ...args: never[]) => unk
  * const abstract: AnyConcreteConstructor = abstract class Abstract { ... }
  * ```
  */
-export type AnyConcreteConstructor = new (arg0: never, ...args: never[]) => unknown;
+export type AnyConcreteConstructor = new (...args: never) => unknown;
 
 /**
  * This type is equivalent to `Promise<T>` but exists to give an explicit signal
  * that this is not a mistake. When Foundry accepts an asynchronous callback the
- * vast majority of the time it is best to use {@link MaybePromise | `MaybePromise`}.
+ * vast majority of the time it is best to use {@linkcode MaybePromise}.
  *
  * By doing it this way the maximum flexibility is given to the definer of the
  * callback. This is okay because typically asynchronous callbacks are simply
  * awaited, meaning that there's no noticeable difference between a `Promise`
- * and {@link MaybePromise | `MaybePromise`}. Even functions like
- * {@link Promise.allSettled | `Promise.allSettled`} function correctly
- * with {@link MaybePromise | `MaybePromise`}.
+ * and {@linkcode MaybePromise}. Even functions like
+ * {@linkcode Promise.allSettled} function correctly
+ * with {@linkcode MaybePromise}.
  *
- * Do not use this type or {@link MaybePromise | `MaybePromise`} for the return
+ * Do not use this type or {@linkcode MaybePromise} for the return
  * type of asynchronous methods on classes. For example for
  * {@link foundry.abstract.Document._preCreate | `Document#_preCreate`} the typing
  * should be `Promise<void>` and not this type. In theory we could use
- * {@link MaybePromise | `MaybePromise`} in this context as well but this seems
+ * {@linkcode MaybePromise} in this context as well but this seems
  * more likely to be confusing than to be helpful.
  *
  * Use this type only in the rare case where a callback's return type must be a
  * `Promise`, for example if `promise.then` or `promise.catch` is explicitly
  * called. Please also writing a comment explaining why
- * {@link MaybePromise | `MaybePromise`} is problematic in this context.
+ * {@linkcode MaybePromise} is problematic in this context.
  */
 export type MustBePromise<T> = Promise<T>;
 
@@ -897,7 +915,7 @@ export type MustBePromise<T> = Promise<T>;
  * callback instead.
  *
  * If it is not sound to provide a non-Promise for whatever reason, see
- * {@link MustBePromise | `MustBePromise`} to declare this more explicitly than simply writing
+ * {@linkcode MustBePromise} to declare this more explicitly than simply writing
  * `Promise<T>`.
  *
  * This should generally not be used in asynchronous methods. For example in
@@ -931,13 +949,11 @@ export type NonNullish = {};
  *
  * Use instead of `{}` when you want to represent an empty object. `{}` actually
  * allows any type that is not `null` or `undefined`. see
- * {@link NonNullish | `NonNullish`} if you want that behavior.
+ * {@linkcode NonNullish} if you want that behavior.
  */
 // It would be unsound to merge into so an interface is not used.
 export type EmptyObject = Record<string, never>;
 
-declare const empty: unique symbol;
-
 /**
  * This helper type helps emulate index signatures for types with incompatible concrete keys.
  *
@@ -975,12 +991,6 @@ export type ShapeWithIndexSignature<
   readonly [K in keyof T & IndexSignature]: K extends keyof PrimaryShape ? PrimaryShape[K] : IndexType;
 };
 
-/**
- * Defer is a utility type that allows you to defer the evaluation of a type.
- * The use cases for this are extremely advanced. In essence they have to do with breaking cycles in evaluation.
- */
-export type Defer<T> = [T][T extends any ? 0 : never];
-
 export type MustBeValidUuid<Uuid extends string, Type extends Document.Type = Document.Type> = _MustBeValidUuid<
   Uuid,
   Uuid,
@@ -1021,11 +1031,6 @@ type _MustBeValidUuid<
       : InvalidUuid<OriginalUuid>
     : `${Type}.${string}` | `${string}.${string}.${Type}.${string}`;
 
-/**
- * Drops the first element of an array
- */
-type DropFirst<T extends AnyArray> = T extends [infer _1, ...infer V] ? V : T;
-
 /**
  * This type is used when you want to use `unknown` in a union. This works because while `T | unknown`
  * will reduce to `unknown`. However by comparison the only way that `T | LazyUnknown` can reduce is
@@ -1038,7 +1043,7 @@ type DropFirst<T extends AnyArray> = T extends [infer _1, ...infer V] ? V : T;
  *
  * The type `{}` isn't actually the type for an empty object. It allows anything except
  * `null`/`undefined` which is why `{} | null | undefined` allows anything to be assigned to it.
- * See {@link NonNullish | `NonNullish`} for a further explanation on why `{}` allows anything
+ * See {@linkcode NonNullish} for a further explanation on why `{}` allows anything
  * besides `null`/`undefined`.
  */
 export type LazyUnknown = NonNullish | null | undefined;
@@ -1086,6 +1091,319 @@ export type Coalesce<T, D, CoalesceType = undefined> = T extends CoalesceType ?
 
 /**
  * Coalesces specifically `null | undefined`. Behaves like `??` does at runtime.
- * See {@link Coalesce | `Coalesce`}.
+ * See {@linkcode Coalesce}.
  */
 export type NullishCoalesce<T, D> = T extends null | undefined ? D : T;
+
+export interface EarlierHook {
+  none: never;
+  init: "none";
+  i18nInit: "none" | "init";
+  setup: "none" | "init" | "i18nInit";
+  ready: "none" | "init" | "i18nInit" | "setup";
+}
+
+/**
+ * A hook that's valid to use in {@linkcode AssumeHookRan}
+ */
+export type InitializationHook = keyof EarlierHook;
+
+/**
+ * All hooks ran so far.
+ *
+ * @example
+ * ```ts
+ * HooksRan<never>;      // never
+ * HooksRan<"none">;     // "none"
+ * HooksRan<"init">;     // "none" | "init"
+ * HooksRan<"i18nInit">; // "none" | "init" | "i18nInit"
+ * HooksRan<"setup">;    // "none" | "init" | "i18nInit" | "setup"
+ * HooksRan<"ready">;    // "none" | "init" | "i18nInit" | "setup" | "ready"
+ * ```
+ */
+export type HooksRan<T extends InitializationHook> = EarlierHook[T] | T;
+type ValidHooksRan = Extract<keyof AssumeHookRan, InitializationHook>;
+
+/**
+ * Various things within Foundry are only initialized after a certain hook is ran.
+ * `InitializedOn` is useful to help model this pattern.
+ */
+export type InitializedOn<
+  InitializedTo,
+  InitializedOnHook extends InitializationHook,
+  BeforeInitialization = InitializedTo | undefined,
+> = [InitializedOnHook] extends [HooksRan<ValidHooksRan>] ? InitializedTo : BeforeInitialization;
+
+/**
+ * Returns the inputted type. This may seem like a useless type but it exists due to limitations
+ * with the syntax of TypeScript interfaces. For example it's a syntax error to write
+ * `interface Example extends typeof SomeClass {}` but `typeof SomeClass` is a reasonable base type
+ * so to work around this you can write `interface Example extends Identity<typeof SomeClass> {}`
+ */
+export type Identity<T extends object> = T;
+
+/**
+ * ### Usage
+ *
+ * Note: See "Background" for an explanation of what a "Discriminated Union" is.
+ *
+ * Use `DiscriminatedUnion` when you want to turn a regular union into a discriminated union. The form
+ * this helper type chooses is
+ * `{ prop1: number; readonly prop2?: never } | { readonly prop1?: never; prop2: string }` as this
+ * is the strictest form of a discriminated union. `readonly prop1?: never` is very similar to
+ * `prop1?: undefined` but `never` is used because with
+ * [`exactOptionalPropertyTypes`](https://www.typescriptlang.org/tsconfig/exactOptionalPropertyTypes.html)
+ * there is an actual difference and `readonly` is there because it prevents erroneous mutation.
+ *
+ * Please note that this type is unsound when you don't know for sure the union can't have
+ * excess properties that interfere with other constituents. For a basic example of this unsoundness:
+ * ```ts
+ * function selectRandom<T, U>(array1: T, array2: U): DiscrimatedUnion<T | U> {
+ *   return (Math.random() > 0.5 ? array1 : array2) as DiscrimatedUnion<T | U>;
+ * }
+ *
+ * const obj1 = { prop1: "foo" };
+ * const obj2: { prop2: number } = { prop1: 1, prop2: "bar" };
+ *
+ * const discriminatedUnion = selectRandom(obj1, obj2)
+ *
+ * // If `selectRandom` returned `T | U` then `discriminatedUnion.prop1` would error.
+ * // However because of unsoundly using `DiscrimatedUnion` it doesn't.
+ * const prop1 = discriminatedUnion.prop1;
+ * //    ^ `string | undefined`.
+ *
+ * console.log(prop1 !== undefined ? prop1.length : 0);
+ * //                                ^ Runtime error the 50% of the time that `prop1` is actually `1` at runtime
+ * ```
+ *
+ * ### Background
+ *
+ * A common unintuitive behavior of unions in TypeScript is that if a property only exists on some
+ * members of the union, then access on that property is not allowed:
+ * ```typescript
+ * const member1 = { prop1: "foo" };
+ * const member2 = { prop2: 1 };
+ * const union = Math.random() > 0.5 ? member1 : member2;
+ * //    ^ { prop1: string; } | { prop2: number; }
+ *
+ * const prop1 = union.prop1;
+ * ```
+ *
+ * This snippet errors at `union.prop1` with:
+ * ```
+ * Property 'prop1' does not exist on type '{ prop1: number; } | { prop2: number; }'.
+ *   Property 'prop1' does not exist on type '{ prop2: number; }'.`
+ * ```
+ *
+ * This error is not very good at explaining why the result can't simply be `number | undefined` but
+ * it can't simply be relaxed. To understand why you need to know that excess properties can always
+ * be assigned to an object. To demonstrate:
+ * ```ts
+ * function takesObj(obj: { prop1: number }) { ... }
+ *
+ * // You may think excess properties aren't allowed because when you try to write code like this,
+ * // it errors.
+ * takesObj({ prop1: 1, prop2: "foo" });
+ * //                   ^ Object literal may only specify known properties, but 'prop2' does not exist in type '{ prop1: number; }'. Did you mean to write 'prop1'?
+ *
+ * // However this is more of a "lint" than a hard error.
+ * const obj = { prop1: 1, prop2: "foo" };
+ * takesObj(obj); // No error
+ * ```
+ *
+ * This means that the type of `union.prop1` would have to be `unknown` at best because at runtime
+ * there could be any excess properties of any type.
+ *
+ * ### Discriminated Unions
+ *
+ * Discriminated unions are a way to get around this issue. There's several possible ways to express
+ * discriminated unions but the most common version is
+ * `{ prop1: number; prop2?: never } | { prop1?: never; prop1: number }`. The key idea is to
+ * put a property that ensures that `undefined` will be read out. Using `never` specifically avoids
+ * some niche issues.
+ *
+ * In fact TypeScript will automatically create a discriminated union in some cases. For example if
+ * you simplify the snippet above:
+ * ```typescript
+ * const discriminatedUnion = Math.random() > 0.5 ? { prop1: 1 } : { prop2: 2 };
+ * //    ^ { prop1: number; prop2?: undefined } | { prop2: number; prop1?: undefined }
+ *
+ * const prop1 = discriminatedUnion.prop1;
+ * //    ^ number | undefined
+ * ```
+ *
+ * You'll see TypeScript now has enough information to give `discriminatedUnion` a better type than
+ * `union` had which now makes `discriminatedUnion.prop1` work.
+ *
+ * See:
+ *
+ * {@link https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions}
+ *
+ * {@link https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-func.html#discriminated-unions}
+ */
+export type DiscriminatedUnion<U extends object> = _DiscriminatedUnion<U, AllKeysOf<U>>;
+
+// Note(LukeAbby): The `extends object` is effectively the same as `extends unknown` but used here
+// to keep `Document.SystemOfType<Document.ModuleSubType>` from being `unknown` in dependencies.
+// Inlining `Extract<..., object>` by comparison causes issues, specifically in not counting as
+// covaraint. This isn't an ideal change to make but it works.
+type _DiscriminatedUnion<U extends object, AllKeys extends AllKeysOf<U>> = U extends object
+  ? [Exclude<AllKeys, keyof U>] extends [never]
+    ? U
+    : U & {
+        readonly [K in Exclude<AllKeys, keyof U>]?: never;
+      }
+  : never;
+
+/**
+ * Picks keys where the value extends `Value`
+ *
+ * @example
+ * ```typescript
+ * type Picked = PickValue<{ type: "coordinates"; x: 123; y: 456; }, number>;
+ * //   ^ { x: 123; y: 456 }
+ * ```
+ */
+export type PickValue<T extends object, Value> = {
+  [K in keyof T as T[K] extends Value ? K : never]: T[K];
+};
+
+/**
+ * Represents a valid JSON value.
+ */
+export type JSONValue =
+  | {
+      readonly [K: string]: JSONValue;
+    }
+  | readonly JSONValue[]
+  | number
+  | string
+  | boolean
+  | null
+  | undefined;
+
+/**
+ * This type represents a constructor such that `typeof SomeConstructor & PhantomConstructor`
+ * simplifies to `typeof SomeConstructor`.
+ */
+export type PhantomConstructor = new (...args: any[]) => unknown;
+
+/**
+ * Effectively equivalent to `str.split(delimiter)` at the type level.
+ */
+export type SplitString<S extends string, Delimiter extends string> = Delimiter extends ""
+  ? ToCharacters<S>
+  : _SplitString<S, Delimiter>;
+
+type ToCharacters<S, Return extends string[] = []> = S extends `${infer C}${infer Rest}`
+  ? ToCharacters<Rest, [...Return, C]>
+  : Return;
+
+type _SplitString<
+  S extends string,
+  Delimiter extends string,
+  Return extends string[] = [],
+> = S extends `${infer Prefix}${Delimiter}${infer Suffix}`
+  ? _SplitString<Suffix, Delimiter, [...Return, Prefix]>
+  : S extends ""
+    ? []
+    : [...Return, S];
+
+export type DeepReadonly<T extends object> = T extends AnyObject | AnyArray
+  ? { readonly [K in keyof T]: _DeepReadonly<T[K]> }
+  : DeepReadonlyComplex<T>;
+
+type _DeepReadonly<T> = T extends object ? DeepReadonly<T> : T;
+
+interface DeepReadonlyComplex<T extends object> extends _DeepReadonlyComplex<T> {}
+
+// @ts-expect-error - This pattern is intrinsically an error.
+// Note(LukeAbby): The two levels here, `DeepReadonlyComplex` and `_DeepReadonlyComplex`, could just be one.
+// However it gives a better type display as two levels.
+interface _DeepReadonlyComplex<T extends object, R extends object = { readonly [K in keyof T]: _DeepReadonly<T[K]> }>
+  extends R,
+    T {}
+
+/**
+ * Currently indistinguishable from `DotKeys` but will eventually avoid `readonly` keys.
+ */
+export type MutableDotKeys<T extends object> = DotKeys<T>;
+
+/**
+ * Currently indistinguishable from `DotKeys` but will eventually avoid keys that can't be deleted.
+ */
+export type DeletableDotKeys<T extends object> = DotKeys<T>;
+
+/**
+ * Gets the valid dotkeys for `T`. Currently only gets keys that are in all items in a union. Later
+ * configuration to loosen this will exist.
+ */
+export type DotKeys<T extends object> = {
+  [K in keyof T]: K | (K extends string ? _DotKeys<T[K], `${K}.`, [T]> : never);
+}[keyof T];
+
+type _DotKeys<T, Prefix extends string = "", Stack extends unknown[] = []> = T extends object
+  ? true extends InStack<T, Stack, 10>
+    ? never
+    : {
+        [K in keyof T]: K extends string ? `${Prefix}${K}` | _DotKeys<T[K], `${Prefix}${K}.`, [T, ...Stack]> : never;
+      }[keyof T]
+  : never;
+
+type InStack<T, Stack extends unknown[], MaxDepth extends number = 99> = Stack["length"] extends MaxDepth
+  ? true
+  : {
+      [K in keyof Stack & `${number}`]: IdentityEquals<T, Stack[K]>;
+    }[keyof Stack & `${number}`];
+
+type IdentityEquals<T, U> =
+  (<V>() => V extends T ? true : false) extends <V>() => V extends U ? true : false ? true : false;
+
+/**
+ * Gets a dot property on `T`.
+ */
+export type GetProperty<T extends object, K extends DotKeys<T>> = _GetProperty<T, K>;
+
+/**
+ * This is causing an issue with TS-Go. See https://github.com/microsoft/typescript-go/issues/1278.
+ */
+type _GetProperty<T, K, Depth extends number[] = []> = K extends keyof T
+  ? T[K]
+  : K extends `${infer First}.${infer Rest}`
+    ? First extends keyof T
+      ? _GetProperty<T[First], Rest, [1, ...Depth]>
+      : never
+    : never;
+
+/**
+ * @deprecated Replaced by {@linkcode Document.SheetClassFor}
+ */
+export type ConfiguredSheetClass<T extends Document.AnyConstructor> = GetKey<
+  GetKey<CONFIG, T["metadata"]["name"]>,
+  "sheetClass",
+  T
+>;
+
+/**
+ * @deprecated Replaced by {@linkcode Document.ObjectClassFor}
+ */
+export type ObjectClass<T extends Document.AnyConstructor> = GetKey<
+  GetKey<CONFIG, T["metadata"]["name"]>,
+  "objectClass",
+  T
+>;
+
+/**
+ * @deprecated Replaced by {@linkcode Document.LayerClassFor}
+ */
+export type LayerClass<T extends Document.AnyConstructor> = GetKey<
+  GetKey<CONFIG, T["metadata"]["name"]>,
+  "layerClass",
+  T
+>;
+
+/**
+ * Actual document types that go in folders
+ * @deprecated No replacement as this was deemed too niche.
+ */
+export type FolderDocumentTypes = Exclude<foundry.CONST.FOLDER_DOCUMENT_TYPES, "Compendium">;