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

checkPidsInSameVersionChain(pids, optionsopt) → {Promise.<object>}

Check whether a set of PIDs belongs to one known version chain.
Parameters:
Name Type Attributes Description
pids Array.<string> PIDs to compare
options object <optional>
 options to pass to SysMetaService.download
Since:
  • 2.39.0
Source:
Throws:
When the version chain cannot be loaded
Type
Error
Returns:
Chain membership details
Type
Promise.<object>

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|null)>}

Get the latest accessible version in the forward version chain.
Parameters:
Name Type Attributes Description
pid string PID to get the latest version for
options object <optional>
 Lookup options
Properties
Name Type Attributes Description
requireComplete boolean <optional>
 Require proof that the end of the version chain was reached
Source:
Throws:
When a complete result is required but cannot be proven
Type
Error
Returns:
Latest accessible PID, or null when the starting PID is inaccessible
Type
Promise.<(string|null)>

getLatestVersions(pids, optionsopt) → {Promise.<Array.<string>>}

Get the conclusive latest version of each PID with bounded concurrency.
Parameters:
Name Type Attributes Description
pids Array.<string> PIDs to map
options object <optional>
 Version lookup options
Properties
Name Type Attributes Description
maxConcurrent number <optional>
 Maximum concurrent lookups
Since:
  • 2.39.0
Source:
Throws:
When any latest-version lookup fails
Type
Error
Returns:
Latest-version PIDs
Type
Promise.<Array.<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, optionsopt) → {Promise.<(string|null)>}

Get the PID that is n number of versions newer or older than the a PID.
Parameters:
Name Type Attributes 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.
options object <optional>
 options to pass to SysMetaService.download
Source:
Throws:
if the requested version is private or missing
Type
Error
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.<SystemMetadata>}

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

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 System Metadata for a given PID is cached.
Parameters:
Name Type Description
pid string the PID to check
Source:
Returns:
resolves to true if the System Metadata 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 SystemMetadata The System Metadata of the version to check for conflicts.
adjSysMeta SystemMetadata The System Metadata 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 System Metadata record 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

checkPidsInSameVersionChain(pids, optionsopt) → {Promise.<object>}

Check whether a set of PIDs belongs to one known version chain.
Parameters:
Name Type Attributes Description
pids Array.<string> PIDs to compare
options object <optional>
 options to pass to SysMetaService.download
Since:
  • 2.39.0
Source:
Throws:
When the version chain cannot be loaded
Type
Error
Returns:
Chain membership details
Type
Promise.<object>

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|null)>}

Get the latest accessible version in the forward version chain.
Parameters:
Name Type Attributes Description
pid string PID to get the latest version for
options object <optional>
 Lookup options
Properties
Name Type Attributes Description
requireComplete boolean <optional>
 Require proof that the end of the version chain was reached
Source:
Throws:
When a complete result is required but cannot be proven
Type
Error
Returns:
Latest accessible PID, or null when the starting PID is inaccessible
Type
Promise.<(string|null)>

getLatestVersions(pids, optionsopt) → {Promise.<Array.<string>>}

Get the conclusive latest version of each PID with bounded concurrency.
Parameters:
Name Type Attributes Description
pids Array.<string> PIDs to map
options object <optional>
 Version lookup options
Properties
Name Type Attributes Description
maxConcurrent number <optional>
 Maximum concurrent lookups
Since:
  • 2.39.0
Source:
Throws:
When any latest-version lookup fails
Type
Error
Returns:
Latest-version PIDs
Type
Promise.<Array.<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, optionsopt) → {Promise.<(string|null)>}

Get the PID that is n number of versions newer or older than the a PID.
Parameters:
Name Type Attributes 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.
options object <optional>
 options to pass to SysMetaService.download
Source:
Throws:
if the requested version is private or missing
Type
Error
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.<SystemMetadata>}

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

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 System Metadata for a given PID is cached.
Parameters:
Name Type Description
pid string the PID to check
Source:
Returns:
resolves to true if the System Metadata 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 SystemMetadata The System Metadata of the version to check for conflicts.
adjSysMeta SystemMetadata The System Metadata 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 System Metadata record is missing necessary date information.
Type
DateConflict | false