api.history.diff()

The change list between two commits of an entity's history.

Part of the Action API · Function reference · Since Action API 0.3 (v0.100.0)

Signature

api.history.diff(
  b: string,
  a?: string,
  ref?: { type: 'campaign' | 'map' | 'character'; id: string },
): Promise<{ summary: string; changes: { path: string; before: unknown; after: unknown }[] }>

Asynchronous — await it.

Parameters

Parameter	Type	Description
`b`	`string`	The commit to diff to. Required.
`a`	`string`	The commit to diff from. Optional: from nothing, so the diff reads `created` and lists every row.
`ref`	`{ type, id }`	Which entity's history. Optional: the map the action is running on.

Returns

summary is the one line the commit list shows. changes is one entry per thing that changed, matched by id, never by position:

`path`	What it is
`row.name`	A column of the entity's own row.
`tables.tokens[<id>]`	A contained row added (`before: null`) or removed (`after: null`).
`tables.tokens[<id>].x`	One column of a contained row.

A JSON column changes as a whole — a character's powers array is one value. The contained tables of a map are mapLayers, tokens, drawings, vblShapes, fogOfWarShapes, mapObjects, and its grants; of a character, equipment, characterRelationships, characterPermissions, grants; of a campaign, its members, grants and every reference-data family.

Example

const [head, prev] = await api.history.commits();
if (!prev) return;
const { summary, changes } = await api.history.diff(head.id, prev.id);
const moved = changes.filter((c) => /^tables\.tokens\[[^\]]+\]\.[xy]$/.test(c.path));
sendMessage(`${summary}: ${moved.length} coordinate${moved.length === 1 ? '' : 's'} changed`);

Needs a map, and the user's own access

As api.history.commits(): an open map, and the user's own read access to the entity. A commit id that is not the entity's answers 404.