@league-of-foundry-developers/foundry-vtt-types 9.280.0 → 12.331.1-beta

package/src/foundry/clipper/index.d.mts

@@ -0,0 +1 @@
+import "./clipper.d.mts";

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

@@ -0,0 +1,274 @@
+import type Document from "./document.d.mts";
+
+export interface DatabaseGetOperation {
+  /**
+   * A query object which identifies the set of Documents retrieved
+   */
+  query: Record<string, unknown>;
+
+  /**
+   * Get requests are never broadcast
+   */
+  broadcast?: false | undefined;
+
+  /**
+   * Return indices only instead of full Document records
+   */
+  index?: boolean | undefined;
+
+  /**
+   * An array of field identifiers which should be indexed
+   */
+  indexFields?: string[] | undefined;
+
+  /**
+   * A compendium collection ID which contains the Documents
+   */
+  pack?: string | null | undefined;
+
+  /**
+   * A parent Document within which Documents are embedded
+   */
+  parent?: foundry.abstract.Document.Any | undefined;
+
+  /**
+   * A parent Document UUID provided when the parent instance is unavailable
+   */
+  parentUuid?: string | undefined;
+}
+
+export interface DatabaseCreateOperation<T extends Document.Internal.Instance.Any = Document.Internal.Instance.Any> {
+  /**
+   * Whether the database operation is broadcast to other connected clients
+   */
+  broadcast: boolean;
+
+  /**
+   * An array of data objects from which to create Documents
+   */
+  data: foundry.data.fields.SchemaField.InnerAssignmentType<Document.Internal.SchemaFor<T>>[];
+
+  /**
+   * Retain the _id values of provided data instead of generating new ids
+   */
+  keepId?: boolean | undefined;
+
+  /**
+   * Retain the _id values of embedded document data instead of generating
+   *    new ids for each embedded document
+   */
+  keepEmbeddedIds?: boolean | undefined;
+
+  /**
+   * The timestamp when the operation was performed
+   */
+  modifiedTime?: number | undefined;
+
+  /**
+   * Block the dispatch of hooks related to this operation
+   */
+  noHook?: boolean | undefined;
+
+  /**
+   * Re-render Applications whose display depends on the created Documents
+   */
+  render?: boolean | undefined;
+
+  /**
+   * Render the sheet Application for any created Documents
+   */
+  renderSheet?: boolean | undefined;
+
+  /**
+   * A parent Document within which Documents are embedded
+   */
+  parent?: foundry.abstract.Document.Any | undefined;
+
+  /**
+   * A compendium collection ID which contains the Documents
+   */
+  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;
+
+  /** @privateRemarks these are added from WorldCollection.importFromCompendium() **/
+  fromCompendium?: boolean | undefined;
+
+  /**
+   * Clear the currently assigned folder
+   */
+  clearFolder?: boolean | undefined;
+
+  /**
+   * Clear the current sort order
+   */
+  clearSort?: boolean | undefined;
+
+  /**
+   * Clear Document ownership
+   */
+  clearOwnership?: boolean | undefined;
+
+  /**
+   * @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;
+}
+
+export interface DatabaseUpdateOperation<T extends Document.Internal.Instance.Any = Document.Internal.Instance.Any> {
+  /**
+   * Whether the database operation is broadcast to other connected clients
+   */
+  broadcast: boolean;
+
+  /**
+   * 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>>[];
+
+  /**
+   * Difference each update object against current Document data and only use
+   * differential data for the update operation
+   */
+  diff?: boolean | undefined;
+
+  /**
+   * The timestamp when the operation was performed
+   */
+  modifiedTime?: number | undefined;
+
+  /**
+   * Merge objects recursively. If false, inner objects will be replaced
+   * explicitly. Use with caution!
+   */
+  recursive?: boolean | undefined;
+
+  /**
+   * Re-render Applications whose display depends on the created Documents
+   */
+  render?: boolean | undefined;
+
+  /**
+   * Block the dispatch of hooks related to this operation
+   */
+  noHook?: boolean | undefined;
+
+  /**
+   * A parent Document within which Documents are embedded
+   */
+  parent?: foundry.abstract.Document.Any | undefined;
+
+  /**
+   * A compendium collection ID which contains the Documents
+   */
+  pack: string | null;
+
+  /**
+   * 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;
+}
+
+export interface DatabaseDeleteOperation {
+  /**
+   * Whether the database operation is broadcast to other connected clients
+   */
+  broadcast: boolean;
+
+  /**
+   * An array of Document ids which should be deleted
+   */
+  ids: string[];
+
+  /**
+   * Delete all documents in the Collection, regardless of _id
+   */
+  deleteAll?: boolean | undefined;
+
+  /**
+   * The timestamp when the operation was performed
+   */
+  modifiedTime?: number | undefined;
+
+  /**
+   * Block the dispatch of hooks related to this operation
+   */
+  noHook?: boolean | undefined;
+
+  /**
+   * Re-render Applications whose display depends on the deleted Documents
+   */
+  render?: boolean | undefined;
+
+  /**
+   * A parent Document within which Documents are embedded
+   */
+  parent?: foundry.abstract.Document.Any | undefined;
+
+  /**
+   * A compendium collection ID which contains the Documents
+   */
+  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;
+}
+
+export interface DatabaseOperationMap {
+  get: DatabaseGetOperation;
+  create: DatabaseCreateOperation;
+  update: DatabaseUpdateOperation;
+  delete: DatabaseDeleteOperation;
+}
+
+export type DatabaseAction = keyof DatabaseOperationMap;
+export type DatabaseOperation = DatabaseOperationMap[keyof DatabaseOperationMap];
+
+export interface DocumentSocketRequest<Action extends DatabaseAction> {
+  /**
+   * The type of Document being transacted
+   */
+  type: string;
+
+  /**
+   * The action of the request
+   */
+  action: Action;
+
+  /**
+   * Operation parameters for the request
+   */
+  operation: DatabaseOperationMap[Action];
+
+  /**
+   * The id of the requesting User
+   */
+  userId: string;
+
+  /**
+   * Should the response be broadcast to other connected clients?
+   */
+  broadcast: boolean;
+}

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

@@ -0,0 +1,190 @@
+import type { ConstructorOf, InexactPartial } from "../../../types/utils.d.mts";
+import type BaseUser from "../documents/user.d.mts";
+import type Document from "./document.d.mts";
+import type {
+  DatabaseCreateOperation,
+  DatabaseDeleteOperation,
+  DatabaseGetOperation,
+  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,
+ * updated, and deleted.
+ */
+declare abstract class DatabaseBackend {
+  /**
+   * Retrieve Documents based on provided query parameters.
+   * @param documentClass - The Document definition
+   * @param operation     - Parameters of the get operation
+   * @param user          - The requesting User
+   * @returns An array of retrieved Document instances or index objects
+   */
+  get<T extends Document.Any>(
+    documentClass: ConstructorOf<T>,
+    operation: DatabaseGetOperation,
+    user?: BaseUser,
+  ): Promise<T>[];
+
+  /**
+   * Retrieve Document instances using the specified operation parameters.
+   * @param documentClass  - The Document class definition
+   * @param operation      - Parameters of the get operation
+   * @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>,
+    operation: DatabaseGetOperation,
+    user?: BaseUser,
+  ): Promise<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
+   * 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 Document instances using provided data and operation parameters.
+   * @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
+   */
+  protected abstract _createDocuments<T extends Document.Any>(
+    documentClass: ConstructorOf<T>,
+    operation: DatabaseCreateOperation<T>,
+    user?: BaseUser,
+  ): Promise<T[]>;
+
+  /**
+   * Update Documents using provided data and context.
+   * It is recommended to use {@link Document.updateDocuments} or {@link 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 Document instances using provided data and operation parameters.
+   * @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
+   */
+  protected abstract _updateDocuments<T extends Document.Any>(
+    documentClass: ConstructorOf<T>,
+    operation: DatabaseUpdateOperation<T>,
+    user: BaseUser,
+  ): Promise<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.
+   * @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 Document instances using provided ids and operation parameters.
+   * @param documentClass - The Document class definition
+   * @param operation     - Parameters of the delete operation
+   * @param user          - The requesting User
+   */
+  protected abstract _deleteDocuments<T extends Document.Any>(
+    documentClass: ConstructorOf<T>,
+    operation: DatabaseDeleteOperation,
+    user: BaseUser,
+  ): Promise<T[]>;
+
+  /**
+   * Get the parent Document (if any) associated with a request context.
+   * @param operation - The requested database operation
+   * @returns The parent Document, or null
+   */
+  _getParent(operation: DatabaseOperation): Promise<Document.Any | null>;
+
+  /**
+   * Describe the scopes which are suitable as the namespace for a flag key
+   */
+  getFlagScopes(): string[];
+
+  /**
+   * Describe the scopes which are suitable as the namespace for a flag key
+   */
+  getCompendiumScopes(): string[];
+
+  /**
+   * Log a database operations message.
+   * @param level   - The logging level
+   * @param message - The message
+   */
+  protected _log(level: LoggingLevels, message: string): void;
+
+  /**
+   * Log a database operation for an embedded document, capturing the action taken and relevant IDs
+   * @param action    - The action performed
+   * @param type      - The document type
+   * @param documents - The documents modified
+   */
+  protected _logOperation(
+    action: string,
+    type: string,
+    documents: Document.Any[],
+    {
+      parent,
+      pack,
+      level,
+    }?: InexactPartial<{
+      /** A parent document */
+      parent: Document.Any;
+
+      /** A compendium pack within which the operation occurred */
+      pack: string;
+
+      /**
+       * The logging level
+       * @defaultValue `"info"`
+       */
+      level: LoggingLevels;
+    }>,
+  ): void;
+
+  /**
+   * Construct a standardized error message given the context of an attempted operation
+   */
+  protected _logError(
+    user: BaseUser,
+    action: string,
+    { parent, pack }?: { parent?: Document.Any; pack?: string },
+  ): string;
+}
+
+export default DatabaseBackend;