Class: VersionTracker

VersionTracker()

VersionTracker walks sysmeta version chains and caches them in memory and in localForage for fast access. It allows getting PIDs at arbitrary stepss from a given PID, fetching full version chains, and listening for updates. A store is created for each unique SysMeta service URL, so multiple VersionTracker instances can coexist without conflicts.

Constructor

new VersionTracker()

Since:
  • 2.34.0
Source:
Example
const vt = new VersionTracker({
 metaServiceUrl: "https://example.com/sysmeta",
})
vt.getNth("pid123", 1).then((pid) => {
 console.log("Next version PID:", pid);
});
const allVersions = await vt.getAllVersions("pid123");
console.log("All versions in chain:", allVersions.prev.versions,
 allVersions.next.versions);

Methods

clearCache() → {Promise.<boolean>}

Clear the entire cache, including in-memory and persistent store.
Source:
Returns:
resolves to true if the cache was cleared
Type
Promise.<boolean>

getAdjacent(pid, forward, optionsopt) → {Promise.<(string|null)>}

Get the PID that is one version older or newer than the given PID.
Parameters:
Name Type Attributes Default Description
pid string The starting PID
forward boolean true True to get the next (newer) version, false for the previous (older) version.
options object <optional>
 options to pass to SysMetaService.download
Source:
Returns:
resolves to the adjacent version PID, or null if no such version exists.
Type
Promise.<(string|null)>

getAllVersions(pid, optionsopt) → {Promise.<{prev: VersionRecord, next: VersionRecord}>}

Get the complete version chain for the given PID.
Parameters:
Name Type Attributes Description
pid string PID to get the chain for
options object <optional>
 options to pass to SysMetaService.download
Source:
Returns:
resolves to an object with 'prev' and 'next' VersionRecords
Type
Promise.<{prev: VersionRecord, next: VersionRecord}>

getAllVersionsOneDirection(startPid, forward, optionsopt) → {Promise.<object>}

Get all versions in one direction (newer or older) from a starting PID.
Parameters:
Name Type Attributes Default Description
startPid string The starting PID
forward boolean true True to get newer versions, false for older
options object <optional>
 options to pass to SysMetaService.download
Source:
Returns:
resolves to a record with the following
Type
Promise.<object>

getLatestVersion(pid, optionsopt) → {Promise.<string>}

Get the latest version in the version chain for the given PID. If the newest versions are private or not found, this will return the last available version.
Parameters:
Name Type Attributes Description
pid string PID to get the latest version for
options object <optional>
 options to pass to SysMetaService.download
Source:
Returns:
resolves to the latest version PID, or the original PID if no newer versions exist or are accessible.
Type
Promise.<string>

getNext(pid, optionsopt) → {Promise.<string>}

Get the next most recent version after the given PID.
Parameters:
Name Type Attributes Description
pid string The PID that is obsoleted by the next version
options object <optional>
 options to pass to SysMetaService.download
Since:
  • 2.34.1
Source:
Returns:
resolves to the next version PID, or null if there is no next version.
Type
Promise.<string>

getNth(pid, steps) → {Promise.<(string|null)>}

Get the PID that is n number of versions newer or older than the a PID.
Parameters:
Name Type Description
pid string The starting PID
steps number Number of versions away from the starting PID. Positive values indicate newer versions, negative values indicate older versions. For example, a step of 1 gets the next version, -1 gets the previous version. A step of 0 returns the original PID.
Source:
Returns:
resolves to the PID at the given number of steps, or null if no such version exists.
Type
Promise.<(string|null)>

getPrev(pid, optionsopt) → {Promise.<string>}

Get the previous version before the given PID.
Parameters:
Name Type Attributes Description
pid string The PID that obsoletes the previous version
options object <optional>
 options to pass to SysMetaService.download
Since:
  • 2.34.1
Source:
Returns:
resolves to the previous version PID, or null if there is no previous version.
Type
Promise.<string>

getSysMeta(pid, optionsopt) → {Promise.<SysMeta>}

Get the SysMeta for a given PID. SysMetaService handles caching, token management, and duplicate fetch prevention.
Parameters:
Name Type Attributes Description
pid string the PID to get SysMeta for
options object <optional>
 options to pass to SysMetaService.download
Source:
Returns:
resolves to the SysMeta object for the PID
Type
Promise.<SysMeta>

getVersions(startPid, steps, optionsopt) → {Promise.<VersionRecord>}

Get version information for a given PID and number of steps.
Parameters:
Name Type Attributes Description
startPid string The starting PID
steps number Number of versions away from the starting PID. Positive values indicate newer versions, negative values indicate older versions. For example, a step of 1 gets the next version, -1 gets the previous version.
options object <optional>
 options to pass to SysMetaService.download
Source:
Returns:
resolves to a record that includes versions found, number of completed steps, and flags for chain completion, privacy, and not-found status.
Type
Promise.<VersionRecord>

isEndOfChain(pid, forward, optionsopt) → {Promise.<boolean>}

Check if the given PID is at the end of its version chain in the given direction.
Parameters:
Name Type Attributes Default Description
pid string PID to check
forward boolean true True to check for next version, false for previous
options object <optional>
 options to pass to SysMetaService.download
Source:
Throws:
if the PID is invalid or SysMeta cannot be retrieved
Type
Error
Returns:
resolves to true if the PID is at the end of the chain in the given direction
Type
Promise.<boolean>

sysMetaIsCached(pid) → {Promise.<boolean>}

Check if the SysMeta for a given PID is cached.
Parameters:
Name Type Description
pid string the PID to check
Source:
Returns:
resolves to true if the SysMeta is cached
Type
Promise.<boolean>

detectDateConflict(sysMeta, adjSysMeta, forward) → {DateConflict|false}

Detect if there is a date conflict between two adjacent versions in the version chain. A conflict occurs when the dateUploaded of an obsoleting version is earlier than that of the obsoleted version, which breaks the expected chronological order.
Parameters:
Name Type Description
sysMeta SysMeta The SysMeta of the version to check for conflicts.
adjSysMeta SysMeta The SysMeta of the adjacent version to compare against.
forward boolean True if adjSysMeta is the obsoleting (newer) version, false if adjSysMeta is the obsoleted (older) version.
Source:
Returns:
A DateConflict object if a conflict is detected, or false if no conflict is found or if either SysMeta is missing necessary date information.
Type
DateConflict | false

VersionTracker(options)

new VersionTracker(options)

Create a new VersionTracker instance.
Parameters:
Name Type Description
options object configuration options
Properties
Name Type Attributes Description
metaServiceUrl string <optional>
 URL of the SysMeta service
maxChainHops number <optional>
 Maximum number of hops in the version chain to cache. Defaults to 200 hops.
ttlMs number | null <optional>
 Time-To-Live for cached records in milliseconds. Defaults to 1 hour. Set to null to disable expiration.
Source:

Methods

clearCache() → {Promise.<boolean>}

Clear the entire cache, including in-memory and persistent store.
Source:
Returns:
resolves to true if the cache was cleared
Type
Promise.<boolean>

getAdjacent(pid, forward, optionsopt) → {Promise.<(string|null)>}

Get the PID that is one version older or newer than the given PID.
Parameters:
Name Type Attributes Default Description
pid string The starting PID
forward boolean true True to get the next (newer) version, false for the previous (older) version.
options object <optional>
 options to pass to SysMetaService.download
Source:
Returns:
resolves to the adjacent version PID, or null if no such version exists.
Type
Promise.<(string|null)>

getAllVersions(pid, optionsopt) → {Promise.<{prev: VersionRecord, next: VersionRecord}>}

Get the complete version chain for the given PID.
Parameters:
Name Type Attributes Description
pid string PID to get the chain for
options object <optional>
 options to pass to SysMetaService.download
Source:
Returns:
resolves to an object with 'prev' and 'next' VersionRecords
Type
Promise.<{prev: VersionRecord, next: VersionRecord}>

getAllVersionsOneDirection(startPid, forward, optionsopt) → {Promise.<object>}

Get all versions in one direction (newer or older) from a starting PID.
Parameters:
Name Type Attributes Default Description
startPid string The starting PID
forward boolean true True to get newer versions, false for older
options object <optional>
 options to pass to SysMetaService.download
Source:
Returns:
resolves to a record with the following
Type
Promise.<object>

getLatestVersion(pid, optionsopt) → {Promise.<string>}

Get the latest version in the version chain for the given PID. If the newest versions are private or not found, this will return the last available version.
Parameters:
Name Type Attributes Description
pid string PID to get the latest version for
options object <optional>
 options to pass to SysMetaService.download
Source:
Returns:
resolves to the latest version PID, or the original PID if no newer versions exist or are accessible.
Type
Promise.<string>

getNext(pid, optionsopt) → {Promise.<string>}

Get the next most recent version after the given PID.
Parameters:
Name Type Attributes Description
pid string The PID that is obsoleted by the next version
options object <optional>
 options to pass to SysMetaService.download
Since:
  • 2.34.1
Source:
Returns:
resolves to the next version PID, or null if there is no next version.
Type
Promise.<string>

getNth(pid, steps) → {Promise.<(string|null)>}

Get the PID that is n number of versions newer or older than the a PID.
Parameters:
Name Type Description
pid string The starting PID
steps number Number of versions away from the starting PID. Positive values indicate newer versions, negative values indicate older versions. For example, a step of 1 gets the next version, -1 gets the previous version. A step of 0 returns the original PID.
Source:
Returns:
resolves to the PID at the given number of steps, or null if no such version exists.
Type
Promise.<(string|null)>

getPrev(pid, optionsopt) → {Promise.<string>}

Get the previous version before the given PID.
Parameters:
Name Type Attributes Description
pid string The PID that obsoletes the previous version
options object <optional>
 options to pass to SysMetaService.download
Since:
  • 2.34.1
Source:
Returns:
resolves to the previous version PID, or null if there is no previous version.
Type
Promise.<string>

getSysMeta(pid, optionsopt) → {Promise.<SysMeta>}

Get the SysMeta for a given PID. SysMetaService handles caching, token management, and duplicate fetch prevention.
Parameters:
Name Type Attributes Description
pid string the PID to get SysMeta for
options object <optional>
 options to pass to SysMetaService.download
Source:
Returns:
resolves to the SysMeta object for the PID
Type
Promise.<SysMeta>

getVersions(startPid, steps, optionsopt) → {Promise.<VersionRecord>}

Get version information for a given PID and number of steps.
Parameters:
Name Type Attributes Description
startPid string The starting PID
steps number Number of versions away from the starting PID. Positive values indicate newer versions, negative values indicate older versions. For example, a step of 1 gets the next version, -1 gets the previous version.
options object <optional>
 options to pass to SysMetaService.download
Source:
Returns:
resolves to a record that includes versions found, number of completed steps, and flags for chain completion, privacy, and not-found status.
Type
Promise.<VersionRecord>

isEndOfChain(pid, forward, optionsopt) → {Promise.<boolean>}

Check if the given PID is at the end of its version chain in the given direction.
Parameters:
Name Type Attributes Default Description
pid string PID to check
forward boolean true True to check for next version, false for previous
options object <optional>
 options to pass to SysMetaService.download
Source:
Throws:
if the PID is invalid or SysMeta cannot be retrieved
Type
Error
Returns:
resolves to true if the PID is at the end of the chain in the given direction
Type
Promise.<boolean>

sysMetaIsCached(pid) → {Promise.<boolean>}

Check if the SysMeta for a given PID is cached.
Parameters:
Name Type Description
pid string the PID to check
Source:
Returns:
resolves to true if the SysMeta is cached
Type
Promise.<boolean>

detectDateConflict(sysMeta, adjSysMeta, forward) → {DateConflict|false}

Detect if there is a date conflict between two adjacent versions in the version chain. A conflict occurs when the dateUploaded of an obsoleting version is earlier than that of the obsoleted version, which breaks the expected chronological order.
Parameters:
Name Type Description
sysMeta SysMeta The SysMeta of the version to check for conflicts.
adjSysMeta SysMeta The SysMeta of the adjacent version to compare against.
forward boolean True if adjSysMeta is the obsoleting (newer) version, false if adjSysMeta is the obsoleted (older) version.
Source:
Returns:
A DateConflict object if a conflict is detected, or false if no conflict is found or if either SysMeta is missing necessary date information.
Type
DateConflict | false