@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.340.1

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

@@ -23,7 +23,7 @@ declare abstract class DatabaseBackend {
   get<T extends Document.AnyConstructor>(
     documentClass: T,
     operation: DatabaseGetOperation,
-    user?: User,
+    user?: User.Implementation,
   ): Promise<FixedInstanceType<T>>[];
 
   /**
@@ -36,12 +36,12 @@ declare abstract class DatabaseBackend {
   protected abstract _getDocuments<T extends Document.AnyConstructor>(
     documentClass: T,
     operation: DatabaseGetOperation,
-    user?: User,
+    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
@@ -50,8 +50,8 @@ declare abstract class DatabaseBackend {
    */
   create<T extends Document.AnyConstructor>(
     documentClass: T,
-    operation: DatabaseCreateOperation<FixedInstanceType<T>>,
-    user?: User,
+    operation: DatabaseBackend.CreateOperation<T>,
+    user?: User.Implementation,
   ): Promise<FixedInstanceType<T>[]>;
 
   /**
@@ -64,12 +64,12 @@ declare abstract class DatabaseBackend {
   protected abstract _createDocuments<T extends Document.AnyConstructor>(
     documentClass: T,
     operation: DatabaseCreateOperation<FixedInstanceType<T>>,
-    user?: User,
+    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
@@ -78,8 +78,8 @@ declare abstract class DatabaseBackend {
    */
   update<T extends Document.AnyConstructor>(
     documentClass: T,
-    operation: DatabaseUpdateOperation<FixedInstanceType<T>>,
-    user?: User,
+    operation: DatabaseBackend.UpdateOperation<T>,
+    user?: User.Implementation,
   ): Promise<FixedInstanceType<T>[]>;
 
   /**
@@ -92,13 +92,13 @@ declare abstract class DatabaseBackend {
   protected abstract _updateDocuments<T extends Document.AnyConstructor>(
     documentClass: T,
     operation: DatabaseUpdateOperation<FixedInstanceType<T>>,
-    user: User,
+    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
@@ -106,8 +106,8 @@ declare abstract class DatabaseBackend {
    */
   delete<T extends Document.AnyConstructor>(
     documentClass: T,
-    operation: DatabaseDeleteOperation,
-    user?: User,
+    operation: DatabaseBackend.DeleteOperation,
+    user?: User.Implementation,
   ): Promise<FixedInstanceType<T>[]>;
 
   /**
@@ -119,7 +119,7 @@ declare abstract class DatabaseBackend {
   protected abstract _deleteDocuments<T extends Document.AnyConstructor>(
     documentClass: T,
     operation: DatabaseDeleteOperation,
-    user: User,
+    user: User.Implementation,
   ): Promise<FixedInstanceType<T>[]>;
 
   /**
@@ -178,7 +178,19 @@ declare abstract class DatabaseBackend {
   /**
    * Construct a standardized error message given the context of an attempted operation
    */
-  protected _logError(user: User, action: string, { parent, pack }?: { parent?: Document.Any; pack?: string }): string;
+  protected _logError(
+    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;