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

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

@@ -1,6 +1,11 @@
 import type Document from "./document.d.mts";
 
-export interface DatabaseGetOperation {
+// A series of types used by the DatabaseBackend.
+// The operation object is picked apart and restructured several times within the DatabaseBackend and ClientDatabaseBackend methods
+// This means that actual functions must use helper types to properly omit properties or explicit undefined
+// Also, the _result property is intentionally left out as it is never present on the client
+
+export interface DatabaseGetOperation<Parent extends Document.Any | null = Document.Any | null> {
   /**
    * A query object which identifies the set of Documents retrieved
    */
@@ -29,7 +34,7 @@ export interface DatabaseGetOperation {
   /**
    * A parent Document within which Documents are embedded
    */
-  parent?: foundry.abstract.Document.Any | undefined;
+  parent?: Parent | null | undefined;
 
   /**
    * A parent Document UUID provided when the parent instance is unavailable
@@ -37,136 +42,144 @@ export interface DatabaseGetOperation {
   parentUuid?: string | undefined;
 }
 
-export interface DatabaseCreateOperation<T extends Document.Internal.Instance.Any = Document.Internal.Instance.Any> {
+export interface DatabaseCreateOperation<
+  CreateData extends object | null | undefined = object | null | undefined,
+  Parent extends Document.Any | null = Document.Any | null,
+  Temporary extends boolean | undefined = boolean | undefined,
+> {
   /**
    * Whether the database operation is broadcast to other connected clients
    */
-  broadcast: boolean;
+  broadcast?: boolean;
 
   /**
    * An array of data objects from which to create Documents
    */
-  data: foundry.data.fields.SchemaField.InnerAssignmentType<Document.Internal.SchemaFor<T>>[];
+  data: CreateData[];
 
   /**
    * Retain the _id values of provided data instead of generating new ids
    */
-  keepId?: boolean | undefined;
+  keepId?: boolean;
 
   /**
    * Retain the _id values of embedded document data instead of generating
    *    new ids for each embedded document
    */
-  keepEmbeddedIds?: boolean | undefined;
+  keepEmbeddedIds?: boolean;
 
   /**
    * The timestamp when the operation was performed
+   * @remarks Set in DatabaseBackend##configureOperation
    */
-  modifiedTime?: number | undefined;
+  modifiedTime: number;
 
   /**
    * Block the dispatch of hooks related to this operation
    */
-  noHook?: boolean | undefined;
+  noHook?: boolean;
 
   /**
    * Re-render Applications whose display depends on the created Documents
+   * @defaultValue `true`
    */
-  render?: boolean | undefined;
+  render: boolean;
 
   /**
    * Render the sheet Application for any created Documents
+   * @defaultValue `false`
    */
-  renderSheet?: boolean | undefined;
+  renderSheet: boolean;
 
   /**
    * A parent Document within which Documents are embedded
    */
-  parent?: foundry.abstract.Document.Any | undefined;
+  parent?: Parent | null;
 
   /**
    * A compendium collection ID which contains the Documents
    */
-  pack: string | null;
+  pack?: string | null;
 
   /**
    * A parent Document UUID provided when the parent instance is unavailable
    */
-  parentUuid?: string | null | undefined;
-
-  /**
-   * An alias for 'data' used internally by the server-side backend
-   */
-  _result?: (string | Record<string, unknown>)[] | undefined;
+  parentUuid?: string | null;
 
   /** @privateRemarks these are added from WorldCollection.importFromCompendium() **/
-  fromCompendium?: boolean | undefined;
+  fromCompendium?: boolean;
 
   /**
    * Clear the currently assigned folder
    */
-  clearFolder?: boolean | undefined;
+  clearFolder?: boolean | null;
 
   /**
    * Clear the current sort order
    */
-  clearSort?: boolean | undefined;
+  clearSort?: boolean | null;
 
   /**
    * Clear Document ownership
    */
-  clearOwnership?: boolean | undefined;
+  clearOwnership?: boolean | null;
 
   /**
    * @deprecated `"It is no longer supported to create temporary documents using the Document.createDocuments API. Use the new Document() constructor instead."`
-   * @remarks No explicit undefined because deprecation message checks `"temporary" in operation`
    */
-  temporary?: boolean | undefined;
+  temporary?: Temporary;
 }
 
-export interface DatabaseUpdateOperation<T extends Document.Internal.Instance.Any = Document.Internal.Instance.Any> {
+export interface DatabaseUpdateOperation<
+  UpdateData extends object | null | undefined = object | null | undefined,
+  Parent extends Document.Any | null = Document.Any | null,
+> {
   /**
    * Whether the database operation is broadcast to other connected clients
    */
-  broadcast: boolean;
+  broadcast?: boolean | null;
 
   /**
    * An array of data objects used to update existing Documents.
    * Each update object must contain the _id of the target Document
    */
-  updates: foundry.data.fields.SchemaField.InnerAssignmentType<Document.Internal.SchemaFor<T>>[];
+  updates: UpdateData[];
 
   /**
    * Difference each update object against current Document data and only use
    * differential data for the update operation
+   * @defaultValue `true`
    */
-  diff?: boolean | undefined;
+  diff: boolean;
 
   /**
    * The timestamp when the operation was performed
+   * @remarks Set in DatabaseBackend##configureOperation
    */
-  modifiedTime?: number | undefined;
+  modifiedTime: number;
 
   /**
    * Merge objects recursively. If false, inner objects will be replaced
    * explicitly. Use with caution!
+   * @defaultValue `true`
    */
-  recursive?: boolean | undefined;
+  recursive: boolean;
 
   /**
    * Re-render Applications whose display depends on the created Documents
+   * @defaultValue `true`
    */
-  render?: boolean | undefined;
+  render: boolean;
 
   /**
    * Block the dispatch of hooks related to this operation
    */
-  noHook?: boolean | undefined;
+  noHook?: boolean | null;
 
   /**
    * A parent Document within which Documents are embedded
    */
-  parent?: foundry.abstract.Document.Any | undefined;
+  parent?: Parent | null;
 
   /**
    * A compendium collection ID which contains the Documents
@@ -176,19 +189,14 @@ export interface DatabaseUpdateOperation<T extends Document.Internal.Instance.An
   /**
    * A parent Document UUID provided when the parent instance is unavailable
    */
-  parentUuid?: string | null | undefined;
-
-  /**
-   * An alias for 'updates' used internally by the server-side backend
-   */
-  _result?: (string | Record<string, unknown>)[] | undefined;
+  parentUuid?: string | null;
 }
 
-export interface DatabaseDeleteOperation {
+export interface DatabaseDeleteOperation<Parent extends Document.Any | null = Document.Any | null> {
   /**
    * Whether the database operation is broadcast to other connected clients
    */
-  broadcast: boolean;
+  broadcast?: boolean;
 
   /**
    * An array of Document ids which should be deleted
@@ -197,43 +205,41 @@ export interface DatabaseDeleteOperation {
 
   /**
    * Delete all documents in the Collection, regardless of _id
+   * @defaultValue `false`
    */
-  deleteAll?: boolean | undefined;
+  deleteAll: boolean;
 
   /**
    * The timestamp when the operation was performed
+   * @remarks Set in DatabaseBackend##configureOperation
    */
-  modifiedTime?: number | undefined;
+  modifiedTime: number;
 
   /**
    * Block the dispatch of hooks related to this operation
    */
-  noHook?: boolean | undefined;
+  noHook?: boolean | null;
 
   /**
    * Re-render Applications whose display depends on the deleted Documents
+   * @defaultValue `true`
    */
-  render?: boolean | undefined;
+  render: boolean;
 
   /**
    * A parent Document within which Documents are embedded
    */
-  parent?: foundry.abstract.Document.Any | undefined;
+  parent?: Parent | null;
 
   /**
    * A compendium collection ID which contains the Documents
    */
-  pack: string | null;
+  pack?: string | null;
 
   /**
    * A parent Document UUID provided when the parent instance is unavailable
    */
-  parentUuid?: string | null | undefined;
-
-  /**
-   * An alias for 'ids' used internally by the server-side backend
-   */
-  _result?: (string | Record<string, unknown>)[] | undefined;
+  parentUuid?: string | null;
 }
 
 export interface DatabaseOperationMap {

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

@@ -1,5 +1,4 @@
-import type { ConstructorOf, InexactPartial } from "../../../types/utils.d.mts";
-import type BaseUser from "../documents/user.d.mts";
+import type { InexactPartial, FixedInstanceType, LoggingLevels } from "#utils";
 import type Document from "./document.d.mts";
 import type {
   DatabaseCreateOperation,
@@ -8,7 +7,6 @@ import type {
   DatabaseOperation,
   DatabaseUpdateOperation,
 } from "./_types.d.mts";
-import type { LoggingLevels } from "../../../types/helperTypes.d.mts";
 
 /**
  * An abstract base class extended on both the client and server which defines how Documents are retrieved, created,
@@ -22,11 +20,11 @@ declare abstract class DatabaseBackend {
    * @param user          - The requesting User
    * @returns An array of retrieved Document instances or index objects
    */
-  get<T extends Document.Any>(
-    documentClass: ConstructorOf<T>,
+  get<T extends Document.AnyConstructor>(
+    documentClass: T,
     operation: DatabaseGetOperation,
-    user?: BaseUser,
-  ): Promise<T>[];
+    user?: User.Implementation,
+  ): Promise<FixedInstanceType<T>>[];
 
   /**
    * Retrieve Document instances using the specified operation parameters.
@@ -35,26 +33,26 @@ declare abstract class DatabaseBackend {
    * @param user           - The requesting User
    * @returns An array of retrieved Document instances or index objects
    */
-  protected abstract _getDocuments<T extends Document.Any>(
-    documentClass: ConstructorOf<T>,
+  protected abstract _getDocuments<T extends Document.AnyConstructor>(
+    documentClass: T,
     operation: DatabaseGetOperation,
-    user?: BaseUser,
-  ): Promise<T[]>;
+    user?: User.Implementation,
+  ): Promise<FixedInstanceType<T>[]>;
 
   /**
    * Create new Documents using provided data and context.
-   * It is recommended to use {@link Document.createDocuments} or {@link Document.create} rather than calling this
+   * It is recommended to use {@link Document.createDocuments | `Document.createDocuments`} or {@link Document.create | `Document.create`} rather than calling this
    * method directly.
    * @param documentClass - The Document class definition
    * @param operation     - Parameters of the create operation
    * @param user          - The requesting User
    * @returns An array of created Document instances
    */
-  create<T extends Document.Any>(
-    documentClass: ConstructorOf<T>,
-    operation: DatabaseCreateOperation<T>,
-    user?: BaseUser,
-  ): Promise<T[]>;
+  create<T extends Document.AnyConstructor>(
+    documentClass: T,
+    operation: DatabaseBackend.CreateOperation<T>,
+    user?: User.Implementation,
+  ): Promise<FixedInstanceType<T>[]>;
 
   /**
    * Create Document instances using provided data and operation parameters.
@@ -63,26 +61,26 @@ declare abstract class DatabaseBackend {
    * @param user          - The requesting User
    * @returns An array of created Document instances
    */
-  protected abstract _createDocuments<T extends Document.Any>(
-    documentClass: ConstructorOf<T>,
-    operation: DatabaseCreateOperation<T>,
-    user?: BaseUser,
-  ): Promise<T[]>;
+  protected abstract _createDocuments<T extends Document.AnyConstructor>(
+    documentClass: T,
+    operation: DatabaseCreateOperation<FixedInstanceType<T>>,
+    user?: User.Implementation,
+  ): Promise<FixedInstanceType<T>[]>;
 
   /**
    * Update Documents using provided data and context.
-   * It is recommended to use {@link Document.updateDocuments} or {@link Document#update} rather than calling this
+   * It is recommended to use {@link Document.updateDocuments | `Document.updateDocuments`} or {@link Document.update | `Document#update`} rather than calling this
    * method directly.
    * @param documentClass - The Document class definition
    * @param operation     - Parameters of the update operation
    * @param user          - The requesting User
    * @returns  An array of updated Document instances
    */
-  update<T extends Document.Any>(
-    documentClass: ConstructorOf<T>,
-    operation: DatabaseUpdateOperation<T>,
-    user?: BaseUser,
-  ): Promise<T[]>;
+  update<T extends Document.AnyConstructor>(
+    documentClass: T,
+    operation: DatabaseBackend.UpdateOperation<T>,
+    user?: User.Implementation,
+  ): Promise<FixedInstanceType<T>[]>;
 
   /**
    * Update Document instances using provided data and operation parameters.
@@ -91,26 +89,26 @@ declare abstract class DatabaseBackend {
    * @param user          - The requesting User
    * @returns  An array of updated Document instances
    */
-  protected abstract _updateDocuments<T extends Document.Any>(
-    documentClass: ConstructorOf<T>,
-    operation: DatabaseUpdateOperation<T>,
-    user: BaseUser,
-  ): Promise<T[]>;
+  protected abstract _updateDocuments<T extends Document.AnyConstructor>(
+    documentClass: T,
+    operation: DatabaseUpdateOperation<FixedInstanceType<T>>,
+    user: User.Implementation,
+  ): Promise<FixedInstanceType<T>[]>;
 
   /**
    * Delete Documents using provided ids and context.
-   * It is recommended to use {@link foundry.abstract.Document.deleteDocuments} or
-   * {@link foundry.abstract.Document#delete} rather than calling this method directly.
+   * It is recommended to use {@link foundry.abstract.Document.deleteDocuments | `foundry.abstract.Document.deleteDocuments`} or
+   * {@link foundry.abstract.Document.delete | `foundry.abstract.Document#delete`} rather than calling this method directly.
    * @param documentClass - The Document class definition
    * @param operation     - Parameters of the delete operation
    * @param user          - The requesting User
    * @returns The deleted Document instances
    */
-  delete<T extends Document.Any>(
-    documentClass: ConstructorOf<T>,
-    operation: DatabaseDeleteOperation,
-    user?: BaseUser,
-  ): Promise<T[]>;
+  delete<T extends Document.AnyConstructor>(
+    documentClass: T,
+    operation: DatabaseBackend.DeleteOperation,
+    user?: User.Implementation,
+  ): Promise<FixedInstanceType<T>[]>;
 
   /**
    * Delete Document instances using provided ids and operation parameters.
@@ -118,11 +116,11 @@ declare abstract class DatabaseBackend {
    * @param operation     - Parameters of the delete operation
    * @param user          - The requesting User
    */
-  protected abstract _deleteDocuments<T extends Document.Any>(
-    documentClass: ConstructorOf<T>,
+  protected abstract _deleteDocuments<T extends Document.AnyConstructor>(
+    documentClass: T,
     operation: DatabaseDeleteOperation,
-    user: BaseUser,
-  ): Promise<T[]>;
+    user: User.Implementation,
+  ): Promise<FixedInstanceType<T>[]>;
 
   /**
    * Get the parent Document (if any) associated with a request context.
@@ -181,10 +179,18 @@ declare abstract class DatabaseBackend {
    * Construct a standardized error message given the context of an attempted operation
    */
   protected _logError(
-    user: BaseUser,
+    user: User.Implementation,
     action: string,
     { parent, pack }?: { parent?: Document.Any; pack?: string },
   ): string;
 }
 
+declare namespace DatabaseBackend {
+  type CreateOperation<T extends Document.AnyConstructor> =
+    Document.Database.CreateOperation<DatabaseCreateOperation> & { data: Document.CreateDataFor<T>[] };
+  type UpdateOperation<T extends Document.AnyConstructor> =
+    Document.Database.UpdateDocumentsOperation<DatabaseUpdateOperation> & { updates: Document.UpdateDataFor<T>[] };
+  type DeleteOperation = Document.Database.DeleteDocumentsOperation<DatabaseDeleteOperation> & { ids: string[] };
+}
+
 export default DatabaseBackend;