Document

abstract. Document

The abstract base class shared by both client and server-side which defines the model for a single document type.

Create a new Document by providing an initial data object.

Interfaces

schema

Members

(static) collectionName :string

The named collection to which this Document belongs.

Type:
  • string

(static) database :DatabaseBackend

The database backend used to execute operations and handle results

Type:
  • DatabaseBackend

(static) documentName :string

The canonical name of this Document type, for example "Actor".

Type:
  • string

(static) implementation :function

Return a reference to the implemented subclass of this base document type.

Type:
  • function

(static) metadata :object

Default metadata which applies to each instance of this Document type.

Type:
  • object

collectionName :string

The named collection to which this Document belongs.

Type:
  • string

data :DocumentData

The base data object for this Document which persists both the original source and any derived data.

Type:
  • DocumentData

documentName :string

The canonical name of this Document type, for example "Actor".

Type:
  • string

id :string|null

The canonical identifier for this Document

Type:
  • string | null

isEmbedded :boolean

Test whether this Document is embedded within a parent Document

Type:
  • boolean

name :string|null

The name of this Document, if it has one assigned

Type:
  • string | null

pack :string|null

An immutable reference to a containing Compendium collection to which this Document belongs.

Type:
  • string | null

parent :Document|null

An immutable reverse-reference to the parent Document to which this embedded Document belongs.

Type:
  • Document | null

Methods

(async, protected, static) _onCreateDocuments(documents, context)

Perform follow-up operations when a set of Documents of this type are created. This is where side effects of creation should be implemented. Post-creation side effects are performed only for the client which requested the operation.

Parameters:
Name Type Description
documents Array.<Document>

The Document instances which were created
context DocumentModificationContext

The context for the modification operation

(async, protected, static) _onDeleteDocuments(documents, context)

Perform follow-up operations when a set of Documents of this type are deleted. This is where side effects of deletion should be implemented. Post-deletion side effects are performed only for the client which requested the operation.

Parameters:
Name Type Description
documents Array.<Document>

The Document instances which were deleted
context DocumentModificationContext

The context for the modification operation

(async, protected, static) _onUpdateDocuments(documents, context)

Perform follow-up operations when a set of Documents of this type are updated. This is where side effects of updates should be implemented. Post-update side effects are performed only for the client which requested the operation.

Parameters:
Name Type Description
documents Array.<Document>

The Document instances which were updated
context DocumentModificationContext

The context for the modification operation

(static) canUserCreate(user) → {boolean}

Test whether a given User has a sufficient role in order to create Documents of this type in general.

Parameters:
Name Type Description
user documents.BaseUser

The User being tested
Returns:

Does the User have a sufficient role to create?

Type
boolean

(async, static) create(dataopt, contextopt) → {Promise.<Document>}

See:
  • Document.createDocuments

Create a new Document using provided input data, saving it to the database.

Examples

Create a World-level Item

const data = [{name: "Special Sword", type: "weapon"}];
const created = await Item.create(data);

Create an Actor-owned Item

const data = [{name: "Special Sword", type: "weapon"}];
const actor = game.actors.getName("My Hero");
const created = await Item.create(data, {parent: actor});

Create an Item in a Compendium pack

const data = [{name: "Special Sword", type: "weapon"}];
const created = await Item.create(data, {pack: "mymodule.mypack"});
Parameters:
Name Type Attributes Default Description
data object <optional>
 {}

Initial data used to create this Document
context DocumentModificationContext <optional>
 {}

Additional context which customizes the creation workflow
Returns:

The created Document instance

Type
Promise.<Document>

(async, static) createDocuments(data, contextopt) → {Promise.<Array.<Document>>}

Create multiple Documents using provided input data. Data is provided as an array of objects where each individual object becomes one new Document.

Examples

Create a single Document

const data = [{name: "New Actor", type: "character", img: "path/to/profile.jpg"}];
const created = await Actor.createDocuments(data);

Create multiple Documents

const data = [{name: "Tim", type: "npc"], [{name: "Tom", type: "npc"}];
const created = await Actor.createDocuments(data);

Create multiple embedded Documents within a parent

const actor = game.actors.getName("Tim");
const data = [{name: "Sword", type: "weapon"}, {name: "Breastplate", type: "equipment"}];
const created = await Item.createDocuments(data, {parent: actor});

Create a Document within a Compendium pack

const data = [{name: "Compendium Actor", type: "character", img: "path/to/profile.jpg"}];
const created = await Actor.createDocuments(data, {pack: "mymodule.mypack"});
Parameters:
Name Type Attributes Default Description
data Array.<object>

An array of data objects used to create multiple documents
context DocumentModificationContext <optional>
 {}

Additional context which customizes the creation workflow
Returns:

An array of created Document instances

Type
Promise.<Array.<Document>>

(async, static) deleteDocuments(ids, contextopt) → {Promise.<Array.<Document>>}

Delete one or multiple existing Documents using an array of provided ids. Data is provided as an array of string ids for the documents to delete.

Examples

Delete a single Document

const tim = game.actors.getName("Tim");
const deleted = await Actor.deleteDocuments([tim.id]);

Delete multiple Documents

const tim = game.actors.getName("Tim");
const tom = game.actors.getName("Tom");
const deleted = await Actor.deleteDocuments([tim.id, tom.id]);

Delete multiple embedded Documents within a parent

const tim = game.actors.getName("Tim");
const sword = tim.items.getName("Sword");
const shield = tim.items.getName("Shield");
const deleted = await Item.deleteDocuments([sword.id, shield.id], parent: actor});

Delete Documents within a Compendium pack

const actor = await pack.getDocument(documentId);
const deleted = await Actor.deleteDocuments([actor.id], {pack: "mymodule.mypack"});
Parameters:
Name Type Attributes Default Description
ids Array.<string>

An array of string ids for the documents to be deleted
context DocumentModificationContext <optional>
 {}

Additional context which customizes the deletion workflow
Returns:

An array of deleted Document instances

Type
Promise.<Array.<Document>>

(async, static) updateDocuments(updates, contextopt) → {Promise.<Array.<Document>>}

Update multiple Document instances using provided differential data. Data is provided as an array of objects where each individual object updates one existing Document.

Examples

Update a single Document

const updates = [{_id: "12ekjf43kj2312ds", name: "Timothy"}];
const updated = await Actor.updateDocuments(updates);

Update multiple Documents

const updates = [{_id: "12ekjf43kj2312ds", name: "Timothy"}, {_id: "kj549dk48k34jk34", name: "Thomas"}]};
const updated = await Actor.updateDocuments(updates);

Update multiple embedded Documents within a parent

const actor = game.actors.getName("Timothy");
const updates = [{_id: sword.id, name: "Magic Sword"}, {_id: shield.id, name: "Magic Shield"}];
const updated = await Item.updateDocuments(updates, {parent: actor});

Update Documents within a Compendium pack

const actor = await pack.getDocument(documentId);
const updated = await Actor.updateDocuments([{_id: actor.id, name: "New Name"}], {pack: "mymodule.mypack"});
Parameters:
Name Type Attributes Default Description
updates Array.<object>

An array of differential data objects, each used to update a single Document
context DocumentModificationContext <optional>
 {}

Additional context which customizes the update workflow
Returns:

An array of updated Document instances

Type
Promise.<Array.<Document>>

(protected) _initialize()

Perform one-time initialization tasks which only occur when the Document is first constructed.

(protected) _onCreate(data, options, userId)

Perform follow-up operations after a Document of this type is created. Post-creation operations occur for all clients after the creation is broadcast.

Parameters:
Name Type Description
data object

The initial data object provided to the document creation request
options object

Additional options which modify the creation request
userId string

The id of the User requesting the document update

(protected) _onDelete(options, userId)

Perform follow-up operations after a Document of this type is deleted. Post-deletion operations occur for all clients after the deletion is broadcast.

Parameters:
Name Type Description
options object

Additional options which modify the deletion request
userId string

The id of the User requesting the document update

(protected) _onUpdate(changed, options, userId)

Perform follow-up operations after a Document of this type is updated. Post-update operations occur for all clients after the update is broadcast.

Parameters:
Name Type Description
changed object

The differential data that was changed relative to the documents prior values
options object

Additional options which modify the update request
userId string

The id of the User requesting the document update

(async, protected) _preCreate(data, options, user)

Perform preliminary operations before a Document of this type is created. Pre-creation operations only occur for the client which requested the operation.

Parameters:
Name Type Description
data object

The initial data object provided to the document creation request
options object

Additional options which modify the creation request
user documents.BaseUser

The User requesting the document creation

(async, protected) _preDelete(options, user)

Perform preliminary operations before a Document of this type is deleted. Pre-delete operations only occur for the client which requested the operation.

Parameters:
Name Type Description
options object

Additional options which modify the deletion request
user documents.BaseUser

The User requesting the document deletion

(async, protected) _preUpdate(changed, options, user)

Perform preliminary operations before a Document of this type is updated. Pre-update operations only occur for the client which requested the operation.

Parameters:
Name Type Description
changed object

The differential data that is changed relative to the documents prior values
options object

Additional options which modify the update request
user documents.BaseUser

The User requesting the document update

canUserModify(user, action, dataopt) → {boolean}

Test whether a given User has permission to perform some action on this Document

Parameters:
Name Type Attributes Description
user documents.BaseUser

The User attempting modification
action string

The attempted action
data object <optional>

Data involved in the attempted action
Returns:

Does the User have permission?

Type
boolean

clone(dataopt, saveopt, contextopt) → {Document|Promise.<Document>}

Clone a document, creating a new document by combining current data with provided overrides. The cloned document is ephemeral and not yet saved to the database.

Parameters:
Name Type Attributes Default Description
data Object <optional>
 {}

Additional data which overrides current document data at the time of creation
save boolean <optional>
 false

Save the clone to the World database?
context DocumentModificationContext <optional>
 {}

Additional context options passed to the create method
Returns:

The cloned Document instance

Type
Document | Promise.<Document>

(async) createEmbeddedDocuments(embeddedName, data, contextopt) → {Promise.<Array.<Document>>}

See:
  • Document.createDocuments

Create multiple embedded Document instances within this parent Document using provided input data.

Parameters:
Name Type Attributes Default Description
embeddedName string

The name of the embedded Document type
data Array.<object>

An array of data objects used to create multiple documents
context DocumentModificationContext <optional>
 {}

Additional context which customizes the creation workflow
Returns:

An array of created Document instances

Type
Promise.<Array.<Document>>

(async) delete(contextopt) → {Promise.<Document>}

See:
  • Document.deleteDocuments

Delete this Document, removing it from the database.

Parameters:
Name Type Attributes Default Description
context DocumentModificationContext <optional>
 {}

Additional context which customizes the deletion workflow
Returns:

The deleted Document instance

Type
Promise.<Document>

(async) deleteEmbeddedDocuments(embeddedName, ids, contextopt) → {Promise.<Array.<Document>>}

See:
  • Document.deleteDocuments

Delete multiple embedded Document instances within a parent Document using provided string ids.

Parameters:
Name Type Attributes Default Description
embeddedName string

The name of the embedded Document type
ids Array.<string>

An array of string ids for each Document to be deleted
context DocumentModificationContext <optional>
 {}

Additional context which customizes the deletion workflow
Returns:

An array of deleted Document instances

Type
Promise.<Array.<Document>>

getEmbeddedCollection(embeddedName) → {Collection}

Obtain a reference to the Array of source data within the data object for a certain embedded Document name

Parameters:
Name Type Description
embeddedName string

The name of the embedded Document type
Returns:

The Collection instance of embedded Documents of the requested type

Type
Collection

getEmbeddedDocument(embeddedName, id, optionsopt) → {Document}

Get an embedded document by it's id from a named collection in the parent document.

Parameters:
Name Type Attributes Description
embeddedName string

The name of the embedded Document type
id string

The id of the child document to retrieve
options object <optional>

Additional options which modify how embedded documents are retrieved

Properties
Name Type Attributes Default Description
strict boolean <optional>
 false

Throw an Error if the requested id does not exist. See Collection#get
Returns:

The retrieved embedded Document instance, or undefined

Type
Document

getFlag(scope, key) → {*}

Get the value of a "flag" for this document See the setFlag method for more details on flags

Parameters:
Name Type Description
scope string

The flag scope which namespaces the key
key string

The flag key
Returns:

The flag value

Type
*

getUserLevel(user) → {number|null}

Get the permission level that a specific User has over this Document, a value in CONST.DOCUMENT_PERMISSION_LEVELS.

Parameters:
Name Type Description
user documents.BaseUser

The User being tested
Returns:

A numeric permission level from CONST.DOCUMENT_PERMISSION_LEVELS or null

Type
number | null

migrateSystemData() → {object}

For Documents which include game system data, migrate the system data object to conform to its latest data model. The data model is defined by the template.json specification included by the game system.

Returns:

The migrated system data object

Type
object

(async) setFlag(scope, key, value) → {Promise.<Document>}

Assign a "flag" to this document. Flags represent key-value type data which can be used to store flexible or arbitrary data required by either the core software, game systems, or user-created modules.

Each flag should be set using a scope which provides a namespace for the flag to help prevent collisions.

Flags set by the core software use the "core" scope. Flags set by game systems or modules should use the canonical name attribute for the module Flags set by an individual world should "world" as the scope.

Flag values can assume almost any data type. Setting a flag value to null will delete that flag.

Parameters:
Name Type Description
scope string

The flag scope which namespaces the key
key string

The flag key
value *

The flag value
Returns:

A Promise resolving to the updated document

Type
Promise.<Document>

testUserPermission(user, permission, options) → {boolean}

Test whether a certain User has a requested permission level (or greater) over the Document

Parameters:
Name Type Description
user documents.BaseUser

The User being tested
permission string | number

The permission level from DOCUMENT_PERMISSION_LEVELS to test
options object

Additional options involved in the permission test

Properties
Name Type Attributes Default Description
exact boolean <optional>
 false

Require the exact permission level requested?
Returns:

Does the user have this permission level over the Document?

Type
boolean

toJSON() → {object}

Convert the Document instance to a primitive object which can be serialized. See DocumentData#toJSON

Returns:

The document data expressed as a plain object

Type
object

toObject(sourceopt) → {object}

Transform the Document instance into a plain object. The created object is an independent copy of the original data. See DocumentData#toObject

Parameters:
Name Type Attributes Default Description
source boolean <optional>
 true

Draw values from the underlying data source rather than transformed values
Returns:

The extracted primitive object

Type
object

(async) unsetFlag(scope, key) → {Promise.<Document>}

Remove a flag assigned to the document

Parameters:
Name Type Description
scope string

The flag scope which namespaces the key
key string

The flag key
Returns:

The updated document instance

Type
Promise.<Document>

(async) update(dataopt, contextopt) → {Promise.<Document>}

See:
  • Document.updateDocuments

Update this Document using incremental data, saving it to the database.

Parameters:
Name Type Attributes Default Description
data object <optional>
 {}

Differential update data which modifies the existing values of this document data
context DocumentModificationContext <optional>
 {}

Additional context which customizes the update workflow
Returns:

The updated Document instance

Type
Promise.<Document>

(async) updateEmbeddedDocuments(embeddedName, updates, contextopt) → {Promise.<Array.<Document>>}

See:
  • Document.updateDocuments

Update multiple embedded Document instances within a parent Document using provided differential data.

Parameters:
Name Type Attributes Default Description
embeddedName string

The name of the embedded Document type
updates Array.<object>

An array of differential data objects, each used to update a single Document
context DocumentModificationContext <optional>
 {}

Additional context which customizes the update workflow
Returns:

An array of updated Document instances

Type
Promise.<Array.<Document>>