Update Base Document Types

types/foundry/common/abstract/_types.d.mts

@@ -1,6 +1,8 @@
 import { DocumentUUID } from "@client/utils/helpers.mjs";
 import { DataField } from "@common/data/fields.mjs";
 import { DataModel, Document } from "./_module.mjs";
+import BaseUser from "@common/documents/user.mjs";
+import { DocumentOwnershipString, UserPermission, UserRoleName } from "@common/constants.mjs";
 
 export type DataSchema = { [K in string]: DataField<unknown, unknown> };
 
@@ -57,6 +59,10 @@ export interface DataModelUpdateOptions {
     restoreDelta?: boolean;
 }
 
+export type DatabaseAction = "get" | "create" | "update" | "delete";
+
+export type DatabaseWriteAction = Exclude<DatabaseAction, "get">;
+
 export interface DatabaseGetOperation<TParent extends Document | null> {
     action: "get";
     /** A query object which identifies the set of Documents retrieved */
@@ -168,14 +174,17 @@ export interface DatabaseDeleteCallbackOptions extends Omit<
     "action" | "deleteAll" | "ids" | "pack" | "parent" | "noHook"
 > {}
 
-export type DatabaseAction = "get" | "create" | "update" | "delete";
-
 export type DatabaseOperation<TParent extends Document | null> =
     | DatabaseGetOperation<TParent>
     | DatabaseCreateOperation<TParent>
     | DatabaseUpdateOperation<TParent>
     | DatabaseDeleteOperation<TParent>;
 
+export type DatabaseWriteOperation<TParent extends Document | null> = Exclude<
+    DatabaseOperation<TParent>,
+    DatabaseGetOperation<TParent>
+>;
+
 export interface DocumentSocketRequest {
     /** The type of Document being transacted */
     type: string;
@@ -188,3 +197,28 @@ export interface DocumentSocketRequest {
     /** Should the response be broadcast to other connected clients? */
     broadcast: boolean;
 }
+
+export type DocumentPermissionTest = (user: BaseUser, document: Document, data?: object) => boolean;
+
+type MetadataPermission = UserRoleName | UserPermission | DocumentOwnershipString | ((...args: unknown[]) => boolean);
+
+export interface DocumentClassMetadata {
+    name: string;
+    label: string;
+    coreTypes: readonly string[];
+    collection: string;
+    embedded: Record<string, string>;
+    permissions: {
+        view: MetadataPermission;
+        create: MetadataPermission;
+        update: MetadataPermission;
+        delete: MetadataPermission;
+    };
+    hasTypeData: boolean;
+    /** If the Document class has type data, can users normally create instances of the "base" type? */
+    baseTypeAllowed?: boolean;
+    indexed: boolean;
+    compendiumIndexFields: string[];
+    preserveOnImport: string[];
+    schemaVersion?: string;
+}

types/foundry/common/abstract/document.d.mts

@@ -1,12 +1,6 @@
 import { DocumentUUID } from "@client/utils/helpers.mjs";
 import { DocumentConstructionContext } from "@common/_types.mjs";
-import {
-    DocumentOwnershipLevel,
-    DocumentOwnershipNumber,
-    UserAction,
-    UserPermission,
-    UserRoleName,
-} from "@common/constants.mjs";
+import { DocumentOwnershipLevel, DocumentOwnershipNumber, UserAction } from "@common/constants.mjs";
 import BaseUser from "@common/documents/user.mjs";
 import { AppV1RenderOptions } from "../../client/appv1/api/application-v1.mjs";
 import { DataField, SourceFromSchema } from "../data/fields.mjs";
@@ -20,6 +14,7 @@ import {
     DatabaseUpdateOperation,
     DataModelValidationOptions,
     DataSchema,
+    DocumentClassMetadata,
 } from "./_types.mjs";
 import DatabaseBackend from "./backend.mjs";
 import DataModel from "./data.mjs";
@@ -54,7 +49,7 @@ export default abstract class Document<
     /* -------------------------------------------- */
 
     /** Default metadata which applies to each instance of this Document type. */
-    static get metadata(): DocumentMetadata;
+    static get metadata(): Readonly<DocumentClassMetadata>;
 
     /**
      * The database backend used to execute operations and handle results.
@@ -701,26 +696,6 @@ export default abstract class Document<
     override toObject(source?: boolean): this["_source"];
 }
 
-type MetadataPermission = UserRoleName | UserPermission | ((...args: unknown[]) => boolean);
-
-export interface DocumentMetadata {
-    name: string;
-    collection: string;
-    label: string;
-    coreTypes: readonly string[];
-    embedded: Record<string, string>;
-    hasTypeData: boolean;
-    indexed: boolean;
-    compendiumIndexFields: string[];
-    permissions: {
-        view: MetadataPermission;
-        create: MetadataPermission;
-        update: MetadataPermission;
-        delete: MetadataPermission;
-    };
-    preserveOnImport: string[];
-}
-
 type _Document = Document<_Document | null>;
 
 declare global {

types/foundry/common/constants.d.mts

@@ -826,6 +826,8 @@ export const AUDIO_CHANNELS: Readonly<{
     interface: "AUDIO.CHANNELS.INTERFACE.label";
 }>;
 
+export type AudioChannel = keyof typeof AUDIO_CHANNELS;
+
 /**
  * The allowed playback modes for an audio Playlist
  * @see https://foundryvtt.com/article/playlists/

types/foundry/common/data/fields.d.mts

@@ -1496,6 +1496,19 @@ export class HueField<
     protected static get _defaults(): NumberFieldOptions<number, boolean, boolean, boolean>;
 }
 
+/**
+ * A special `ForeignDocumentField` which defines the original author of a document.
+ * This can only be changed later by GM users.
+ */
+export class DocumentAuthorField<
+    TModelProp extends string | abstract.Document = abstract.Document,
+    TRequired extends boolean = true,
+    TNullable extends boolean = true,
+    THasInitial extends boolean = true,
+> extends ForeignDocumentField<TModelProp, TRequired, TNullable, THasInitial> {
+    protected static override get _defaults(): StringFieldOptions<string, boolean, boolean, boolean>;
+}
+
 /** A special `ObjectField` which captures a mapping of User IDs to Document permission levels. */
 export class DocumentOwnershipField extends ObjectField<{ [K in string]?: DocumentOwnershipNumber }> {
     protected static override get _defaults(): ObjectFieldOptions<
@@ -1830,7 +1843,7 @@ export class JavaScriptField<
 /**
  * A nullable set field used to reference a set of specific Scene Level documents.
  */
-export class SceneLevelsSetField extends SetField<DocumentIdField<string>> {
+export class SceneLevelsSetField extends SetField<DocumentIdField<string, true, false, true>> {
     /**
      * @param options Options which configure the behavior of the field
      * @param context Additional context which describes the field

types/foundry/common/documents/active-effect.d.mts

@@ -1,43 +1,30 @@
 import { DatabaseCreateCallbackOptions } from "@common/abstract/_types.mjs";
-import {
-    ActiveEffectDurationUnit,
-    ActiveEffectShowIcon,
-    DocumentOwnershipLevel,
-    ImageFilePath,
-    UserAction,
-} from "@common/constants.mjs";
-import { Document, DocumentMetadata } from "../abstract/_module.mjs";
+import { ActiveEffectDurationUnit, ActiveEffectShowIcon, ImageFilePath } from "@common/constants.mjs";
+import { Document, DocumentClassMetadata } from "../abstract/_module.mjs";
 import * as fields from "../data/fields.mjs";
-import { ActorUUID, BaseActor, BaseCombat, BaseItem, BaseUser, ItemUUID } from "./_module.mjs";
+import { ActorUUID, BaseActor, BaseCombat, BaseFolder, BaseItem, BaseUser, ItemUUID } from "./_module.mjs";
 
 /**
- * The ActiveEffect document model.
- * @param data    Initial data from which to construct the document.
- * @param context Construction context options
+ * The ActiveEffect Document.
+ * Defines the DataSchema and common behaviors for an ActiveEffect which are shared between both client and server.
  */
-export default class BaseActiveEffect<TParent extends BaseActor | BaseItem<BaseActor | null> | null> extends Document<
-    TParent,
-    ActiveEffectSchema
-> {
+export default class BaseActiveEffect<
+    TParent extends BaseActor | BaseItem<BaseActor | null> | null = BaseActor | BaseItem<BaseActor | null> | null,
+> extends Document<TParent, ActiveEffectSchema> {
     /* -------------------------------------------- */
     /*  Model Configuration                         */
     /* -------------------------------------------- */
 
-    static override get metadata(): ActiveEffectMetadata;
+    static override get metadata(): Readonly<ActiveEffectMetadata>;
 
     static override defineSchema(): ActiveEffectSchema;
 
-    /* -------------------------------------------- */
-    /*  Model Methods                               */
-    /* -------------------------------------------- */
+    static override LOCALIZATION_PREFIXES: string[];
 
-    override canUserModify(user: BaseUser, action: UserAction, data?: object): boolean;
+    /** The default icon used for newly created ActiveEffect documents */
+    static DEFAULT_ICON: string;
 
-    override testUserPermission(
-        user: BaseUser,
-        permission: DocumentOwnershipLevel,
-        { exact }?: { exact?: boolean },
-    ): boolean;
+    static override canUserCreate(user: BaseUser): boolean;
 
     /* -------------------------------------------- */
     /*  Database Event Handlers                     */
@@ -50,34 +37,55 @@ export default class BaseActiveEffect<TParent extends BaseActor | BaseItem<BaseA
     ): Promise<boolean | void>;
 }
 
-export default interface BaseActiveEffect<TParent extends BaseActor | BaseItem<BaseActor | null> | null>
+export default interface BaseActiveEffect<
+    TParent extends BaseActor | BaseItem<BaseActor | null> | null = BaseActor | BaseItem<BaseActor | null> | null,
+>
     extends Document<TParent, ActiveEffectSchema>, fields.ModelPropsFromSchema<ActiveEffectSchema> {
     get documentName(): ActiveEffectMetadata["name"];
+
+    get folder(): BaseFolder | null;
 }
 
-export interface ActiveEffectMetadata extends DocumentMetadata {
+export interface ActiveEffectMetadata extends DocumentClassMetadata {
     name: "ActiveEffect";
     collection: "effects";
+    hasTypeData: true;
+    baseTypeAllowed: true;
+    indexed: true;
+    compendiumIndexFields: ["_id", "name", "img", "type", "sort", "folder"];
     label: "DOCUMENT.ActiveEffect";
-    isEmbedded: true;
+    labelPlural: "DOCUMENT.ActiveEffects";
 }
 
 type ActiveEffectSchema = {
+    /** The _id which uniquely identifies this ActiveEffect document */
     _id: fields.DocumentIdField;
+    /** The name of this ActiveEffect */
     name: fields.StringField<string, string, true, false, false>;
-    system: fields.TypeDataField;
+    /** An image file path which provides the artwork for this ActiveEffect */
+    img: fields.FilePathField<ImageFilePath>;
+    /** An ActorEffect subtype which configures the system data model applied */
     type: fields.StringField<string, string, false, true, true>;
+    /** They system data object which is defined by the system data model */
+    system: fields.TypeDataField;
+    /** Is this ActiveEffect disabled? */
     disabled: fields.BooleanField;
     start: fields.SchemaField<EffectStartSchema, EffectStartSource, EffectStartData, true, true, true>;
     duration: fields.SchemaField<EffectDurationSchema>;
     description: fields.HTMLField;
-    img: fields.FilePathField<ImageFilePath>;
     origin: fields.DocumentUUIDField<ActorUUID | ItemUUID>;
     tint: fields.ColorField;
     transfer: fields.BooleanField;
     statuses: fields.SetField<fields.StringField<string, string, true, false, false>>;
+    /** Is the icon for this ActiveEffect displayed? */
     showIcon: fields.NumberField<ActiveEffectShowIcon, ActiveEffectShowIcon, true, false, true>;
+    /** The Folder which contains this ActiveEffect */
+    folder: fields.ForeignDocumentField<BaseFolder>;
+    /** The numeric sort value which orders this ActiveEffect relative to its siblings */
+    sort: fields.IntegerSortField;
+    /** An object of optional key/value flags */
     flags: fields.DocumentFlagsField;
+    /** An object containing document metadata */
     _stats: fields.DocumentStatsField;
 };
 

types/foundry/common/documents/actor-delta.d.mts

@@ -1,56 +1,46 @@
-import { DocumentOwnershipLevel, ImageFilePath, UserAction } from "@common/constants.mjs";
+import { ImageFilePath } from "@common/constants.mjs";
 import { DocumentConstructionContext } from "../_types.mjs";
 import * as abstract from "../abstract/_module.mjs";
 import { TombstoneDataSchema } from "../data/data.mjs";
 import * as fields from "../data/fields.mjs";
 import Collection from "../utils/collection.mjs";
-import { BaseActiveEffect, BaseActor, BaseItem, BaseToken, BaseUser } from "./_module.mjs";
+import { BaseActiveEffect, BaseActor, BaseItem, BaseToken } from "./_module.mjs";
 import { ItemSchema } from "./item.mjs";
 
 /**
- * The Document definition for an ActorDelta.
+ * The ActorDelta Document.
  * Defines the DataSchema and common behaviors for an ActorDelta which are shared between both client and server.
  * ActorDeltas store a delta that can be applied to a particular Actor in order to produce a new Actor.
- *
- * @param data    Initial data used to construct the ActorDelta.
- * @param context Construction context options.
  */
-export default class BaseActorDelta<TParent extends BaseToken | null> extends abstract.Document<
+export default class BaseActorDelta<TParent extends BaseToken | null = BaseToken | null> extends abstract.Document<
     TParent,
     ActorDeltaSchema
 > {
     /* -------------------------------------------- */
     /*  Model Configuration                         */
     /* -------------------------------------------- */
 
-    static override readonly metadata: ActorDeltaMetadata;
+    static override readonly metadata: Readonly<ActorDeltaMetadata>;
 
     static override defineSchema(): ActorDeltaSchema;
 
-    override canUserModify(user: BaseUser, action: UserAction, data?: Record<string, unknown>): boolean;
-
-    override testUserPermission(
-        user: BaseUser,
-        permission: DocumentOwnershipLevel,
-        { exact }?: { exact?: boolean },
-    ): boolean;
-
     /* -------------------------------------------- */
     /*  Methods                                     */
     /* -------------------------------------------- */
 
+    override getUserLevel(user: foundry.documents.BaseUser): CONST.DocumentOwnershipNumber;
+
     /**
      * Retrieve the base actor's collection, if it exists.
-     * @param collectionName  The collection name.
+     * @param collectionName The collection name.
      */
     getBaseCollection(collectionName: string): Collection<string, BaseActor> | undefined;
 
     /**
      * Apply an ActorDelta to an Actor and return the resultant synthetic Actor.
-     * @param {ActorDelta} delta  The ActorDelta.
-     * @param {Actor} baseActor   The base Actor.
-     * @param {object} [context]  Context to supply to synthetic Actor instantiation.
-     * @returns {Actor|null}
+     * @param delta The ActorDelta.
+     * @param baseActor The base Actor.
+     * @param context Context to supply to synthetic Actor instantiation.
      */
     static applyDelta(
         delta: BaseActorDelta<BaseToken | null>,
@@ -59,10 +49,12 @@ export default class BaseActorDelta<TParent extends BaseToken | null> extends ab
     ): BaseActor;
 }
 
-export default interface BaseActorDelta<TParent extends BaseToken | null>
-    extends abstract.Document<TParent, ActorDeltaSchema>, fields.ModelPropsFromSchema<ActorDeltaSchema> {}
+export default interface BaseActorDelta<TParent extends BaseToken | null = BaseToken | null>
+    extends abstract.Document<TParent, ActorDeltaSchema>, fields.ModelPropsFromSchema<ActorDeltaSchema> {
+    readonly items: abstract.EmbeddedCollection<BaseItem<BaseActor>>;
+}
 
-interface ActorDeltaMetadata extends abstract.DocumentMetadata {
+interface ActorDeltaMetadata extends abstract.DocumentClassMetadata {
     name: "ActorDelta";
     collection: "delta";
     label: "DOCUMENT.ActorDelta";
@@ -75,6 +67,7 @@ interface ActorDeltaMetadata extends abstract.DocumentMetadata {
 }
 
 type ActorDeltaSchema = {
+    /** The _id which uniquely identifies this ActorDelta document */
     _id: fields.DocumentIdField;
     name: fields.StringField<string, string, false, true, true>;
     type: fields.StringField<string, string, false, true, true>;