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

package/src/types/helperTypes.d.mts

@@ -0,0 +1,389 @@
+import type { DatabaseOperationMap, Operation } from "../foundry/common/abstract/document.d.mts";
+import type Document from "../foundry/common/abstract/document.d.mts";
+import type { ConfiguredDocuments } from "./documentConfiguration.d.mts";
+import type { AnyFunction, AnyObject, EmptyObject } from "./utils.d.mts";
+
+export type ModuleRequiredOrOptional<Name extends string> = Name extends keyof RequiredModules ? never : undefined;
+
+export type ConfiguredModuleData<Name extends string> = Name extends keyof ModuleConfig
+  ? ModuleConfig[Name]
+  : EmptyObject;
+
+export type ConfiguredModule<Name extends string> =
+  ModuleRequiredOrOptional<Name> extends never
+    ? ConfiguredModuleData<Name>
+    :
+        | ({ active: true } & ConfiguredModuleData<Name>)
+        // flawed, can't use `key in module` this way, but omitting the Partial Record type kills nullish
+        // collocating, which is probably the better DX.
+        | ({ active: false } & Record<keyof ConfiguredModuleData<Name>, undefined>);
+
+/** Keys of functions of console.log / globalThis.logger */
+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;
+
+/**
+ * `Partial` is usually the wrong type.
+ * In order to make it easier to audit unintentional uses of `Partial` this type is provided.
+ *
+ * ### Picking the right helper type
+ * - Favor `NullishProps` whenever it is valid. Allowing both `null` and
+ *   `undefined` is convenient for the end user and it is very common that
+ *   wherever `undefined` is valid so is `null`. For some examples it is valid
+ *   for `options.prop ??= "default"`, `options.prop ||= "default"`,
+ *   `if (options.prop) { ... }`, `if (options.prop == null)`, or so on.
+ * - Use `IntentionalPartial` when an explicit `undefined` is problematic but
+ *   leaving off the property entirely is fine. This primarily occurs when
+ *   patterns like `options = { ...defaultOptions, ...options }`,
+ *   `Object.assign({}, defaultOptions, options)`,
+ *   `foundry.utils.mergeObject(defaultOptions, options)`, or so on.
+ *
+ *   Note that {@link foundry.utils.mergeObject | `foundry.utils.mergeObject`}
+ *   also expands the object. So once `ExpandsTo` exists you should also use
+ *   that helper type.
+ *
+ *   What these patterns have in common is that if `options` looks like
+ *   `{ prop: undefined }` that will override whatever is in `defaultOptions`
+ *   and may cause issues. Note that even if you see one of these patterns you
+ *   also need to ensure that `undefined` would cause issues down the road
+ *   before using `IntentionalPartial` as it could be an intended way of
+ *   resetting a property.
+ * - Use `InexactPartial` when `null` is problematic but `undefined` is not.
+ *   The most common time this shows up is with the pattern
+ *   `exampleFunction({ prop = "foo" } = {}) { ... }`.
+ */
+export type IntentionalPartial<T> = Partial<T>;
+
+/**
+ * This type is used to make a constraint where `T` must be statically known to overlap with `U`.
+ *
+ * @example
+ * ```ts
+ * // The `const T` allows inference to be a bit more specific. This is useful for a utility type like this.`
+ * function takesNumber<const T>(input: OverlapsWith<T, number>): void {
+ *   // This function body is an example of a method this might be useful for.
+ *   // If the input isn't an number it simply returns in this case.
+ *   if (typeof input !== "number") {
+ *       return;
+ *   }
+ *
+ *   // Assumes, unchecked, that `element` is a number.
+ *   // This means an input like `number[] | string[]` would be unsound as it could be a string.
+ *   element + 1;
+ * }
+ *
+ * takesNumber(1); // Ok!
+ * takesNumber("foo"); // Error, statically known to never an number and so presumed to be a mistake.
+ * takesNumber(Math.random() > 0.5 ? 1 : "foo"); // Ok, `"foo"` doesn't actually cause any runtime issues, it was just disallowed above because then it'd never do anything useful.
+ * ```
+ */
+export type OverlapsWith<T, U> = [Extract<T, U>, any] extends [U, Extract<T, U>] ? T : U extends T ? T : U;
+
+/**
+ * Used to build a constraint where `T` to overlap with `Item[]` but disallows unrelated arrays.
+ * 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.
+ *
+ * @example
+ * ```ts
+ * // The `const T` allows inference to be a bit more specific. This is useful for a utility type like this.`
+ * function takesNumericArray<const T>(input: ArrayOverlaps<T, number>): void {
+ *   // This function body is an example of a method this might be useful for.
+ *   // If the input isn't an array it simply returns in this case.
+ *   if (!Array.isArray(input)) {
+ *       return;
+ *   }
+ *
+ *   for (const element of input) {
+ *       // Assumes, unchecked, that `element` is a number.
+ *       // This means an input like `number[] | string[]` would be unsound as it could be a string.
+ *       element + 1;
+ *   }
+ * }
+ *
+ * takesNumericArray([1, 2, 3]); // Ok!
+ * takesNumericArray("foo"); // Error, statically known to never an array and so presumed to be a mistake.
+ * takesNumericArray(Math.random() > 0.5 ? [1, 2, 3] : "foo"); // Ok, `"foo"` doesn't actually cause any runtime issues, it was just disallowed above because then it'd never do anything useful.
+ * 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[];
+
+/**
+ * Use this whenever a type is given that should match some constraint but is
+ * not guaranteed to. For example when additional properties can be declaration
+ * merged into an interface. When the type does not conform then `ConformTo` is
+ * used instead.
+ *
+ * See `MustConform` for a version that throws a compilation error when the type
+ * cannot be statically known to conform.
+ */
+export type MakeConform<T, ConformTo> = [T] extends [ConformTo] ? T : ConformTo;
+
+/**
+ * This is useful when you want to ensure that a type conforms to a certain
+ * constraint. If it is not guaranteed to conform then a compilation error is
+ * thrown. This makes it too conservative in some cases.
+ */
+export type MustConform<T extends ConformTo, ConformTo> = T;
+
+/**
+ * This allows you to treat all interfaces as a plain object. But beware, if the
+ * interface represents a function, array, or constructor then these will be
+ * stripped from the interface.
+ *
+ * This is generally intended for cases where an interface is given in order to
+ * be declaration merged and then must be assigned to a plain object type.
+ *
+ * The constraint `T extends object` is used because `object` includes functions
+ * and arrays etc. This is crucial to allow interfaces to be given to this type.
+ */
+export type InterfaceToObject<T extends object> = {
+  // Mapped types are no-ops on most types (even primitives like string) but for
+  // functions, classes, and arrays they convert them to "proper" objects by
+  // stripping constructors/function signatures. One side effect is a type like
+  // `() => number` will result in `{}`.
+  [K in keyof T]: T[K];
+};
+
+/**
+ * This is a helper type that allows you to ensure that a record conforms to a
+ * certain shape. This is useful when you want to ensure that a record has all
+ * keys of a certain type.
+ *
+ * When a value does not conform it is replaced with `never` to indicate that
+ * there is an issue.
+ */
+export type ConformRecord<T extends object, V> = {
+  [K in keyof T]: T[K] extends V ? T[K] : never;
+};
+
+/**
+ * This is a helper type that gets the right DatabaseOperation (including the
+ * proper options) for a particular Document type.
+ */
+export type DatabaseOperationsFor<
+  Name extends Document.Type,
+  ConcreteOperation extends Operation,
+> = DatabaseOperationMap[Name][ConcreteOperation];
+
+/**
+ * Converts a regular function type into a function derived from a method.
+ *
+ * Methods have a special exception in TypeScript that allows unsound subtyping
+ * that unfortunately has been deeply engrained into not just JavaScript codebases
+ * but the core APIs of JavaScript itself in the DOM.
+ *
+ * It might seem odd to want to opt-in to this unsoundness but it's unfortunately
+ * useful in several cases, such as when you have a property like
+ * `prop: ((arg: Options) => number) | undefined` and you want to meet the expectations
+ * from other similar methods.
+ *
+ * @example
+ * ```typescript
+ * declare class ExampleBaseClass {
+ *     // This demonstrates a typical example of where the allowed unsoundness is useful.
+ *     methodOne(arg: { x: string }): number;
+ *
+ *     // This helps demonstrates an example that may be easier to recognize as unsound.
+ *     methodTwo(arg: string): number;
+ *
+ *     functionProperty: (arg: string) => number;
+ *     methodLikeProperty: ToMethod<(arg: string) => number>;
+ * }
+ *
+ * // TypeScript allows this without any errors.
+ * declare class MethodSubclassing extends ExampleBaseClass {
+ *     // It's a very common thing for subclasses to ask for extra arguments.
+ *     methodOne(arg: { x: string; y: string }): number;
+ *
+ *     // Only taking `"foo" | "bar"` should seem pretty unsound.
+ *     // The above is actually equally unsound but it's less obvious to many people.
+ *     methodTwo(arg: "foo" | "bar"): number;
+ * }
+ *
+ * const exampleMethodSubclass: ExampleBaseClass = new MethodSubclassing();
+ *
+ * // This is allowed, however at runtime `MethodSubclassing#methodOne` could
+ * // will almost certainly error as it has the required property `y`.
+ * // The reason why there's no errors is an intentional unsoundness in TypeScript.
+ * exampleMethodSubclass.methodOne({ x: "foo" });
+ *
+ * // Similarly this is allowed.
+ * // Both methods show taking arguments that are 'subtypes' of the original.
+ * // In the case of functions this is unsound as demonstrated because in both
+ * // examples you're substituting a function that has to be able to be called
+ * // with a wide variety of arguments with one that will error for many of them.
+ * exampleMethodSubclass.methodTwo("lorem");
+ *
+ * declare class PropertySubclassing extends ExampleBaseClass {
+ *     // This errors right here. This preventative error is because of the prior
+ *     // explained unsoundness. It errors here because there's really only 3
+ *     // places to error at compile time to prevent a runtime error:
+ *     // 1. At the call site when a subclass is used unsoundly. Unfortunately
+ *     //    at this point it's too late to know for certain if it's a subclass
+ *     //    or not. For example there could be a guarded condition to avoid
+ *     //    subclasses that TypeScript can't possibly track.
+ *     // 2. When trying to assign `PropertySubclassing` to `ExampleBaseClass`.
+ *     //    This would be a feasible alternative but would likely come as a
+ *     //    surprise as the subclass could have been used for quite a while
+ *     //    before trying to be assigned to its superclass.
+ *     // 3. Error at the definition. This is where TypeScript has chosen to error.
+ *     //    The error is unfortunately not the most intuitive but it is correct.
+ *     functionProperty: (arg: "foo" | "bar") => number;
+ * }
+ *
+ * declare class MethodLikeSubclassing {
+ *     // This is unsound but by using the `ToMethod` in the parent class it's allowed.
+ *     methodLikeProperty: (arg: "foo" | "bar") => number;
+ * }
+ * ```
+ *
+ * The TypeScript FAQ explains this in a way that may either be intuitive and
+ * explain all lingering questions or be confusing and muddle the waters.
+ * It's also worth mentioning that it claims all function parameters work this way,
+ * 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
+ */
+export type ToMethod<T extends AnyFunction> = {
+  method(...args: Parameters<T>): ReturnType<T>;
+}["method"];
+
+// Deprecated types, to be removed in the first stable v12 release or at the latest v13.
+
+/**
+ * @deprecated {@link Document.SystemType | `Document.SystemType`}.
+ */
+type DocumentTypeWithTypeData = Document.SystemType;
+
+/**
+ * @deprecated {@link Document.AnyConstructor | `Document.ConstructorDataFor`}.
+ */
+export type ConstructorDataType<T extends Document.AnyConstructor> = Document.ConstructorDataFor<T>;
+
+/**
+ * @deprecated {@link Document.AnyConstructor | `Document.AnyConstructor`}.
+ */
+export type DocumentConstructor = Document.AnyConstructor;
+
+/**
+ * @deprecated {@link Document.ToConfiguredClass | `Document.ToConfiguredClass`}.
+ */
+export type ConfiguredDocumentClass<ConcreteDocument extends Document.AnyConstructor> =
+  Document.ToConfiguredClass<ConcreteDocument>;
+
+/**
+ * @deprecated {@link Document.ToConfiguredInstance | `Document.Configured.Instance`}.
+ */
+export type ConfiguredDocumentInstance<ConcreteDocument extends Document.AnyConstructor> =
+  Document.ToConfiguredInstance<ConcreteDocument>;
+
+/**
+ * @deprecated {@link Document.Type | `Document.Type`}.
+ */
+export type DocumentType = Document.Type;
+
+/**
+ * @deprecated {@link Document.PlaceableType | `Document.PlaceableType`}.
+ */
+export type PlaceableDocumentType = Document.PlaceableType;
+
+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
+  | {
+      [K in keyof T]?: never;
+    };
+
+/**
+ * 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;
+}[keyof O];
+
+/**
+ * @deprecated {@link Document.SubTypesOf | `Document.SubTypesOf`}.
+ */
+export type DocumentSubTypes<T extends Document.Type> = Document.SubTypesOf<T>;
+
+/**
+ * @deprecated {@link Document.ConfiguredClassForName | `Document.ConfiguredClassForName`}.
+ */
+export type ConfiguredDocumentClassForName<Name extends Document.Type> = ConfiguredDocuments[Name];
+
+/**
+ * @deprecated {@link Document.ConfiguredInstanceForName | `Document.ConfiguredInstanceForName`}.
+ */
+export type ConfiguredDocumentInstanceForName<Name extends Document.Type> = Document.ConfiguredInstanceForName<Name>;
+
+/**
+ * @deprecated {@link Document.ConfiguredObjectClassForName | `Document.ConfiguredObjectClassForName`}.
+ */
+export type ConfiguredObjectClassForName<Name extends Document.PlaceableType> =
+  Document.ConfiguredObjectClassForName<Name>;
+
+/**
+ * @deprecated {@link PlaceablesLayer.ConfiguredClassForName | `PlaceablesLayer.ConfiguredClassForName`}.
+ */
+export type ConfiguredLayerClassForName<Name extends Document.PlaceableType> = CONFIG[Name]["layerClass"];
+
+/**
+ * See {@link Document.ConfiguredDataForName | `Document.ConfiguredDataForName`}.
+ */
+export type ConfiguredData<Name extends string> = Document.ConfiguredDataForName<MakeConform<Name, Document.Type>>;
+
+/**
+ * See {@link Document.ConfiguredDataForName | `Document.ConfiguredDataForName`}.
+ */
+export type ConfiguredSource<Name extends string> = Document.ConfiguredDataForName<MakeConform<Name, Document.Type>>;
+
+/**
+ * See {@link Document.ConfiguredFlagsForName | `Document.ConfiguredFlagsForName`}.
+ */
+export type ConfiguredFlags<Name extends string> = Document.ConfiguredFlagsForName<MakeConform<Name, Document.Type>>;
+
+/**
+ * @deprecated {@link Document.ToObjectFalseType | `Document.ToObjectFalseType`}.
+ */
+export type ToObjectFalseType<T> = Document.ToObjectFalseType<MakeConform<T, Document.Internal.Instance.Any>>;
+
+/**
+ * @deprecated {@link PropertyKey | `PropertyKey`}
+ */
+export type AnyKey = keyof any;

package/src/types/index.d.mts

@@ -0,0 +1,4 @@
+import "./augments/index.d.mts";
+import "./config.d.mts";
+import "./documentConfiguration.d.mts";
+import "./utils.d.mts";