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

package/src/foundry/common/abstract/embedded-collection-delta.d.mts

@@ -0,0 +1,96 @@
+import type { InexactPartial } from "../../../types/utils.d.mts";
+import type Document from "./document.d.mts";
+import type EmbeddedCollection from "./embedded-collection.d.mts";
+
+/**
+ * An embedded collection delta contains delta source objects that can be compared against other objects inside a base
+ * embedded collection, and generate new embedded Documents by combining them.
+ */
+export default class EmbeddedCollectionDelta<
+  ContainedDocument extends foundry.abstract.Document.Any,
+  ParentDataModel extends foundry.abstract.Document.Any,
+> extends EmbeddedCollection<ContainedDocument, ParentDataModel> {
+  /**
+   * A convenience getter to return the corresponding base collection.
+   */
+  get baseCollection(): EmbeddedCollection<ContainedDocument, ParentDataModel>;
+
+  /**
+   * A convenience getter to return the corresponding synthetic collection.
+   */
+  get syntheticCollection(): EmbeddedCollection<ContainedDocument, ParentDataModel>;
+
+  override createDocument(
+    data: ContainedDocument["_source"][],
+    context: Document.ConstructionContext<Document.Any | null>,
+  ): ContainedDocument;
+
+  protected override initialize(
+    options: InexactPartial<
+      {
+        /**
+         * @defaultValue `false`
+         */
+        full: boolean;
+      } & Document.ConstructionContext<ParentDataModel["parent"]>
+    >,
+  ): void;
+
+  protected override _initializeDocument(
+    data: ContainedDocument["_source"][],
+    options: Document.ConstructionContext<ParentDataModel["parent"]>,
+  ): void;
+
+  protected override _createOrUpdate(
+    data: ContainedDocument["_source"][][],
+    options?: Parameters<ContainedDocument["updateSource"]>[1],
+  ): void;
+
+  /**
+   * Determine whether a given ID is managed directly by this collection delta or inherited from the base collection.
+   * @param key - The Document ID
+   */
+  manages(key: string): boolean;
+
+  /**
+   * Determine whether a given ID exists as a tombstone Document in the collection delta.
+   * @param key - The DocumentID
+   */
+  isTombstone(key: string): boolean;
+
+  /**
+   * Restore a Document so that it is no longer managed by the collection delta and instead inherits from the base Document.
+   * @param id - The Document ID
+   * @returns The restored Document
+   */
+  restoreDocument(id: string): Promise<ContainedDocument>;
+
+  /**
+   * Restore the given Documents so that they are no longer managed by the collection delta and instead inherit directly
+   * from their counterparts in the base Actor.
+   * @param ids - The IDs of the Documents to restore.
+   * @returns An array of updated Document instances.
+   */
+  restoreDocuments(ids: string[]): Promise<ContainedDocument[]>;
+
+  override set(
+    key: string,
+    value: ContainedDocument,
+    options?: InexactPartial<{ modifySource: boolean; restoreDelta: boolean }>,
+  ): this;
+
+  protected override _set(
+    key: string,
+    value: ContainedDocument,
+    options?: InexactPartial<{
+      /**
+       * @defaultValue `false`
+       */
+      restoreDelta: boolean;
+    }>,
+  ): void;
+
+  delete(key: string, options?: { modifySource?: boolean }): boolean;
+
+  protected override _delete(key: string, options: Record<string, unknown>): void;
+}

package/src/foundry/common/abstract/embedded-collection.d.mts

@@ -0,0 +1,252 @@
+import type { ConstructorOf, InexactPartial } from "../../../types/utils.d.mts";
+import type _Collection from "../utils/collection.d.mts";
+import type { DatabaseAction, DatabaseOperation } from "./_types.d.mts";
+import type Document from "./document.d.mts";
+
+// Fix for "Class 'Collection<ContainedDocument>' defines instance member property 'get',
+// but extended class 'EmbeddedCollection<ContainedDocument, ParentDataModel>' defines it as instance member function."
+type Collection<T> = Omit<_Collection<T>, "set" | "delete" | "get">;
+
+interface CollectionConstructor {
+  new (): Collection<any>;
+  new <T>(entries?: readonly (readonly [string, T])[] | null): Collection<T>;
+  new <T>(iterable: Iterable<readonly [string, T]>): Collection<T>;
+  readonly [Symbol.species]: CollectionConstructor;
+  readonly prototype: Collection<any>;
+}
+
+declare const Collection: CollectionConstructor;
+
+/**
+ * An extension of the Collection.
+ * Used for the specific task of containing embedded Document instances within a parent Document.
+ */
+declare class EmbeddedCollection<
+  ContainedDocument extends foundry.abstract.Document.Any,
+  ParentDataModel extends foundry.abstract.Document.Any,
+> extends Collection<ContainedDocument> {
+  /**
+   * @param name          - The name of this collection in the parent Document.
+   * @param parent        - The parent DataModel instance to which this collection belongs
+   * @param sourceArray   - The source data array for the collection in the parent Document data
+   */
+  constructor(name: string, parent: ParentDataModel, sourceArray: ContainedDocument["_source"][]);
+
+  /**
+   * The Document implementation used to construct instances within this collection
+   */
+  readonly documentClass: ConstructorOf<ContainedDocument>;
+
+  /**
+   * The name of this collection in the parent Document.
+   */
+  readonly name: string;
+
+  /**
+   * The parent DataModel to which this EmbeddedCollection instance belongs.
+   */
+  readonly model: ParentDataModel;
+
+  /**
+   * Has this embedded collection been initialized as a one-time workflow?
+   * @defaultValue `false`
+   */
+  protected _initialized: boolean;
+
+  /**
+   * The source data array from which the embedded collection is created
+   */
+  protected readonly _source: ContainedDocument["_source"][];
+
+  /**
+   * Record the set of document ids where the Document was not initialized because of invalid source data
+   */
+  invalidDocumentIds: Set<string>;
+
+  /**
+   * Instantiate a Document for inclusion in the Collection
+   */
+  createDocument(
+    data: ContainedDocument["_source"][],
+    context: Document.ConstructionContext<Document.Any | null>,
+  ): ContainedDocument;
+
+  /**
+   * Initialize the EmbeddedCollection object by constructing its contained Document instances
+   * @param options - Initialization options
+   */
+  protected initialize(options: Document.ConstructionContext<ContainedDocument>): void;
+
+  /**
+   * Initialize an embedded document and store it in the collection.
+   * @param data    - The Document data.
+   * @param options - Options to configure Document initialization.
+   */
+  protected _initializeDocument(
+    data: ContainedDocument["_source"][],
+    options: Document.ConstructionContext<ContainedDocument>,
+  ): void;
+
+  /**
+   * Log warnings or errors when a Document is found to be invalid.
+   * @param id      - The invalid Document's ID.
+   * @param err     - The validation error
+   * @param options - Options to configure invalid Document handling.
+   */
+  _handleInvalidDocument(
+    id: string,
+    err: Error,
+    options: InexactPartial<{
+      /**
+       * Whether to throw an error or only log a warning.
+       */
+      strict: boolean;
+    }>,
+  ): void;
+
+  /**
+   * Get an element from the EmbeddedCollection by its ID.
+   * @param id      - The ID of the Embedded Document to retrieve.
+   * @param options - Additional options to configure retrieval.
+   */
+  get(
+    key: string,
+    options?: InexactPartial<{
+      /**
+       * Throw an Error if the requested Embedded Document does not exist.
+       * @defaultValue `false`
+       */
+      strict: false;
+      /**
+       * Allow retrieving an invalid Embedded Document.
+       * @defaultValue `false`
+       */
+      invalid: false;
+    }>,
+  ): ContainedDocument | undefined;
+  /**
+   * Get an element from the EmbeddedCollection by its ID.
+   * @param id      - The ID of the Embedded Document to retrieve.
+   * @param options - Additional options to configure retrieval.
+   */
+  get(id: string, options: { strict: true; invalid?: false }): ContainedDocument;
+  /**
+   * Get an element from the EmbeddedCollection by its ID.
+   * @param id      - The ID of the Embedded Document to retrieve.
+   * @param options - Additional options to configure retrieval.
+   */
+  get(id: string, options: { strict?: boolean; invalid: true }): unknown;
+
+  /**
+   * Add an item to the collection
+   * @param key     - The embedded Document ID
+   * @param value   - The embedded Document instance
+   * @param options - Additional options to the set operation
+   */
+  set(
+    key: string,
+    value: ContainedDocument,
+    options?: InexactPartial<{
+      /**
+       * Whether to modify the collection's source as part of the operation.
+       * @defaultValue `true`
+       */
+      modifySource: boolean;
+    }>,
+  ): this;
+
+  /**
+   * Modify the underlying source array to include the Document.
+   * @param key   - The Document ID Key
+   * @param value - The Document
+   */
+  protected _set(key: string, value: ContainedDocument): void;
+
+  /**
+   * @param key     - The embedded Document ID.
+   * @param options - Additional options to the delete operation.
+   */
+  delete(
+    key: string,
+    options?: {
+      /**
+       * Whether to modify the collection's source as part of the operation.
+       */
+      modifySource?: boolean;
+    },
+  ): boolean;
+
+  /**
+   * Remove the value from the underlying source array.
+   * @param key     - The Document ID key.
+   * @param options - Additional options to configure deletion behavior.
+   */
+  protected _delete(key: string, options: Record<string, unknown>): void;
+
+  /**
+   * Update an EmbeddedCollection using an array of provided document data.
+   * @param changes - An array of provided Document data
+   * @param options - Additional options which modify how the collection is updated
+   */
+  update(changes: ContainedDocument["_source"][][], options?: Record<string, unknown>): void;
+
+  protected _createOrUpdate(
+    data: ContainedDocument["_source"][][],
+    options?: Parameters<ContainedDocument["updateSource"]>[1],
+  ): void;
+
+  // TODO: Improve typing on invalid documents
+  /**
+   * Obtain a temporary Document instance for a document id which currently has invalid source data.
+   * @param id      - A document ID with invalid source data.
+   * @param options - Additional options to configure retrieval.
+   * @returns An in-memory instance for the invalid Document
+   * @throws If strict is true and the requested ID is not in the set of invalid IDs for this collection.
+   */
+  getInvalid(
+    id: string,
+    options?: {
+      /**
+       * Throw an Error if the requested ID is not in the set of invalid IDs for this collection
+       */
+      strict?: false;
+    },
+  ): unknown;
+  getInvalid(
+    id: string,
+    options: {
+      /**
+       * Throw an Error if the requested ID is not in the set of invalid IDs for this collection
+       */
+      strict: true;
+    },
+  ): unknown;
+
+  /**
+   * Convert the EmbeddedCollection to an array of simple objects.
+   * @param source - Draw data for contained Documents from the underlying data source?
+   *                 (default: `true`)
+   * @returns The extracted array of primitive objects
+   */
+  toObject(source?: true): ContainedDocument["_source"][];
+  toObject(source: false): ReturnType<ContainedDocument["schema"]["toObject"]>[];
+
+  /**
+   * Follow-up actions to take when a database operation modifies Documents in this EmbeddedCollection.
+   * @param action    - The database action performed
+   * @param documents - The array of modified Documents
+   * @param result    - The result of the database operation
+   * @param operation - Database operation details
+   * @param user      - The User who performed the operation
+   * @internal
+   */
+  _onModifyContents(
+    action: DatabaseAction,
+    documents: foundry.abstract.Document.Any[],
+    result: unknown,
+    operation: DatabaseOperation,
+    user: foundry.documents.BaseUser,
+  ): void;
+}
+
+export default EmbeddedCollection;

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

@@ -0,0 +1,13 @@
+// In Foundry itself this file contains re-exports of these other modules.
+// Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
+// While `.mts` could work, to avoid `import/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import/extensions */
+
+export { default as DataModel } from "./data.mjs";
+export { default as TypeDataModel } from "./type-data.mjs";
+export { default as Document } from "./document.mjs";
+export { default as DocumentSocketResponse } from "./socket.mjs";
+export { default as DatabaseBackend } from "./backend.mjs";
+export { default as EmbeddedCollection } from "./embedded-collection.mjs";
+export { default as EmbeddedCollectionDelta } from "./embedded-collection-delta.mjs";
+export { default as SingletonEmbeddedCollection } from "./singleton-collection.mjs";

package/src/foundry/common/abstract/singleton-collection.d.mts

@@ -0,0 +1,19 @@
+import type EmbeddedCollection from "./embedded-collection.d.mts";
+
+/**
+ * This class provides a {@link Collection} wrapper around a singleton embedded Document so that it can be interacted
+ * with via a common interface.
+ */
+export default class SingletonEmbeddedCollection<
+  ContainedDocument extends foundry.abstract.Document.Any,
+  ParentDataModel extends foundry.abstract.Document.Any,
+> extends EmbeddedCollection<ContainedDocument, ParentDataModel> {
+  /**
+   * @throws `Cannot create singleton embedded ${embeddedName} [${key}] in parent ${parentName} `  + `[${this.model.id}] as it already has one assigned.`
+   */
+  override set(key: string, value: ContainedDocument): this;
+
+  protected override _set(key: string, value: ContainedDocument): void;
+
+  protected override _delete(key: string, options: Record<string, unknown>): void;
+}

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

@@ -0,0 +1,36 @@
+import type { DocumentType } from "../../../types/helperTypes.d.mts";
+import type { DatabaseAction, DatabaseOperation, DocumentSocketRequest } from "./_types.d.mts";
+
+/**
+ * The data structure of a modifyDocument socket response.
+ */
+declare class DocumentSocketResponse<Action extends DatabaseAction> {
+  /**
+   * Prepare a response for an incoming request.
+   * @param request - The incoming request that is being responded to
+   */
+  constructor(request: DocumentSocketRequest<Action>);
+
+  /** The type of Document being transacted. */
+  type: DocumentType | undefined;
+
+  /** The database action that was performed. */
+  action: Action | undefined;
+
+  /** Was this response broadcast to other connected clients? */
+  broadcast: boolean | undefined;
+
+  /** The database operation that was requested. */
+  operation: DatabaseOperation | undefined;
+
+  /** The identifier of the requesting user. */
+  userId: string | undefined;
+
+  /** The result of the request. Present if successful */
+  result: Record<string, unknown>[] | string[] | undefined;
+
+  /** An error that occurred. Present if unsuccessful */
+  error: Error | undefined;
+}
+
+export default DocumentSocketResponse;