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 offsets from a given PID, fetching full version chains, and listening for updates. It also supports manually adding a new version to the chain (e.g. when a document has been updated in the editor and the new version is known). 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:
Examples
const vt = new VersionTracker({
 metaServiceUrl: "https://example.com/sysmeta",
})
vt.getNth("pid123", 1).then((result) => {
 console.log("Next version PID:", result.pid);
});
const fullChain = await vt.getFullChain("pid123");
console.log("All versions in chain:", fullChain.prev, fullChain.next);
// Get a singleton instance for a specific SysMeta service URL
// This will create a new instance if it doesn't exist yet.
const vt = VersionTracker.get("https://example.com/sysmeta");

Methods

addVersion(prevPid, newPid, sysMetaopt)

Manually register that `newPid` obsoletes (comes after) `prevPid`. Useful when an external editor just created a brand‑new revision so the chain can be updated immediately without refetching SysMeta. If `sysMeta` for the new PID is already available, pass it to avoid a network round‑trip; otherwise the tracker will fetch it lazily when first requested.
Parameters:
Name Type Attributes Default Description
prevPid string the PID of the previous version
newPid string the PID of the new version
sysMeta SysMeta <optional>
 null optional SysMeta object for the new version.
Source:

clear() → {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, ignoreEndopt, withMetaopt) → {Promise.<{pid: string, prev: VersionResult, next:VersionResult}>}

Get the version before and after the given PID, if available.
Parameters:
Name Type Attributes Default Description
pid string the PID to get adjacent versions for
ignoreEnd boolean <optional>
 false If true, ignore end flags and continue walking the chain even if it appears complete.
withMeta boolean <optional>
 false If true, the SysMeta will be fetched if not already available in the cache.
Since:
  • 2.34.1
Source:
Returns:
- resolves to an object with `pid`, `prev`, and `next` properties. `prev` and `next` are either PIDs or objects with { pid, sysMeta } if `withMeta` is true. If no previous or next version is found, the respective property will be null.
Type
Promise.<{pid: string, prev: VersionResult, next:VersionResult}>

getFullChain(pid, ignoreEndopt, withMetaopt) → {Promise.<VersionRecord>}

Get the complete version chain for the given PID.
Parameters:
Name Type Attributes Default Description
pid string PID to get the chain for
ignoreEnd boolean <optional>
 false Re‑probe past cached end flags
withMeta boolean <optional>
 false If true, return arrays of { pid, sysMeta } instead of bare PIDs.
Source:
Returns:
- resolves to an object with `prev`, `next`, `sysMeta`, `endPrev`, and `endNext` properties.
Type
Promise.<VersionRecord>

getLatestVersion(pid, ignoreEndopt, withMetaopt) → {Promise.<(string|VersionResult)>}

Get the latest version PID in the version chain for the given PID.
Parameters:
Name Type Attributes Default Description
pid string the PID to get the latest version for
ignoreEnd boolean <optional>
 false If true, ignore end flags and continue walking the chain even if it appears complete. This is useful for re-checking if a newer version exists.
withMeta boolean <optional>
 false If true, the SysMeta will be fetched if not already available in the cache.
Source:
Returns:
- resolves to the latest PID in the chain, or an object with { pid, sysMeta } if `withMeta` is true. If no versions are found, resolves to the original PID.
Type
Promise.<(string|VersionResult)>

getNext(pid, ignoreEndopt, withMetaopt) → {Promise.<VersionResult>}

Get the next most recent version after the given PID.
Parameters:
Name Type Attributes Default Description
pid string the PID to get the next version for
ignoreEnd boolean <optional>
 false If true, ignore end flags and continue walking the chain even if it appears complete.
withMeta boolean <optional>
 false If true, the SysMeta will be fetched if not already available in the cache.
Since:
  • 2.34.1
Source:
Returns:
- resolves to the next version PID or an object with { pid, sysMeta } if `withMeta` is true. If no next version is found, resolves to the original PID.
Type
Promise.<VersionResult>

getNth(pid, offset, ignoreEndopt, withMetaopt) → {Promise.<(VersionResult|string|null)>}

Get the PID that is `offset` earlier or later in the version chain relative to the given `pid`.
Parameters:
Name Type Attributes Default Description
pid string the PID to start from
offset number the number of steps to move in the chain. 0 = same PID, +n newer, -n older
ignoreEnd boolean <optional>
 false Set to true to allow walking beyond cached chain end (e.g. to re-check whether there's a newer version)
withMeta boolean <optional>
 false If true, return arrays of { pid, sysMeta } instead of bare PIDs.
Source:
Returns:
- resolves to the requested PID at the given offset, or null if no such version exists. If `withMeta` is true, resolves to an object with { pid, sysMeta }.
Type
Promise.<(VersionResult|string|null)>

getPrev(pid, ignoreEndopt, withMetaopt) → {Promise.<VersionResult>}

Get the previous version before the given PID.
Parameters:
Name Type Attributes Default Description
pid string the PID to get the previous version for
ignoreEnd boolean <optional>
 false If true, ignore end flags and continue walking the chain even if it appears complete.
withMeta boolean <optional>
 false If true, the SysMeta will be fetched if not already available in the cache.
Since:
  • 2.34.1
Source:
Returns:
- resolves to the previous version PID or an object with { pid, sysMeta } if `withMeta` is true. If no previous version is found, resolves to the original PID.
Type
Promise.<VersionResult>

refresh(pid) → {Promise.<object>}

Refresh the version chain for the given PID by removing it from the cache and re-fetching the full chain from the SysMeta service.
Parameters:
Name Type Description
pid string the PID to refresh
Source:
Returns:
- resolves to the refreshed chain object
Type
Promise.<object>

setTTL(ms)

Set the Time-To-Live (TTL) for cached records.
Parameters:
Name Type Description
ms number the TTL in milliseconds
Source:

getToken() → {Promise.<string>}

Ensure the user is authenticated and has a valid token.
Source:
Returns:
- resolves to the user's token
Type
Promise.<string>

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 URL of the SysMeta service
store localforage <optional>
 optional localForage instance for persistent caching. If not provided, a new instance will be created
ttlMs number <optional>
 Time-To-Live for cached records in milliseconds. Defaults to 24 hours (1 day).
maxChainHops number <optional>
 Maximum number of hops in the version chain to cache. Defaults to 200 hops.
maxCacheRecords number <optional>
 Maximum number of in-memory cache records. Defaults to 5000.
Source:

Methods

addVersion(prevPid, newPid, sysMetaopt)

Manually register that `newPid` obsoletes (comes after) `prevPid`. Useful when an external editor just created a brand‑new revision so the chain can be updated immediately without refetching SysMeta. If `sysMeta` for the new PID is already available, pass it to avoid a network round‑trip; otherwise the tracker will fetch it lazily when first requested.
Parameters:
Name Type Attributes Default Description
prevPid string the PID of the previous version
newPid string the PID of the new version
sysMeta SysMeta <optional>
 null optional SysMeta object for the new version.
Source:

clear() → {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, ignoreEndopt, withMetaopt) → {Promise.<{pid: string, prev: VersionResult, next:VersionResult}>}

Get the version before and after the given PID, if available.
Parameters:
Name Type Attributes Default Description
pid string the PID to get adjacent versions for
ignoreEnd boolean <optional>
 false If true, ignore end flags and continue walking the chain even if it appears complete.
withMeta boolean <optional>
 false If true, the SysMeta will be fetched if not already available in the cache.
Since:
  • 2.34.1
Source:
Returns:
- resolves to an object with `pid`, `prev`, and `next` properties. `prev` and `next` are either PIDs or objects with { pid, sysMeta } if `withMeta` is true. If no previous or next version is found, the respective property will be null.
Type
Promise.<{pid: string, prev: VersionResult, next:VersionResult}>

getFullChain(pid, ignoreEndopt, withMetaopt) → {Promise.<VersionRecord>}

Get the complete version chain for the given PID.
Parameters:
Name Type Attributes Default Description
pid string PID to get the chain for
ignoreEnd boolean <optional>
 false Re‑probe past cached end flags
withMeta boolean <optional>
 false If true, return arrays of { pid, sysMeta } instead of bare PIDs.
Source:
Returns:
- resolves to an object with `prev`, `next`, `sysMeta`, `endPrev`, and `endNext` properties.
Type
Promise.<VersionRecord>

getLatestVersion(pid, ignoreEndopt, withMetaopt) → {Promise.<(string|VersionResult)>}

Get the latest version PID in the version chain for the given PID.
Parameters:
Name Type Attributes Default Description
pid string the PID to get the latest version for
ignoreEnd boolean <optional>
 false If true, ignore end flags and continue walking the chain even if it appears complete. This is useful for re-checking if a newer version exists.
withMeta boolean <optional>
 false If true, the SysMeta will be fetched if not already available in the cache.
Source:
Returns:
- resolves to the latest PID in the chain, or an object with { pid, sysMeta } if `withMeta` is true. If no versions are found, resolves to the original PID.
Type
Promise.<(string|VersionResult)>

getNext(pid, ignoreEndopt, withMetaopt) → {Promise.<VersionResult>}

Get the next most recent version after the given PID.
Parameters:
Name Type Attributes Default Description
pid string the PID to get the next version for
ignoreEnd boolean <optional>
 false If true, ignore end flags and continue walking the chain even if it appears complete.
withMeta boolean <optional>
 false If true, the SysMeta will be fetched if not already available in the cache.
Since:
  • 2.34.1
Source:
Returns:
- resolves to the next version PID or an object with { pid, sysMeta } if `withMeta` is true. If no next version is found, resolves to the original PID.
Type
Promise.<VersionResult>

getNth(pid, offset, ignoreEndopt, withMetaopt) → {Promise.<(VersionResult|string|null)>}

Get the PID that is `offset` earlier or later in the version chain relative to the given `pid`.
Parameters:
Name Type Attributes Default Description
pid string the PID to start from
offset number the number of steps to move in the chain. 0 = same PID, +n newer, -n older
ignoreEnd boolean <optional>
 false Set to true to allow walking beyond cached chain end (e.g. to re-check whether there's a newer version)
withMeta boolean <optional>
 false If true, return arrays of { pid, sysMeta } instead of bare PIDs.
Source:
Returns:
- resolves to the requested PID at the given offset, or null if no such version exists. If `withMeta` is true, resolves to an object with { pid, sysMeta }.
Type
Promise.<(VersionResult|string|null)>

getPrev(pid, ignoreEndopt, withMetaopt) → {Promise.<VersionResult>}

Get the previous version before the given PID.
Parameters:
Name Type Attributes Default Description
pid string the PID to get the previous version for
ignoreEnd boolean <optional>
 false If true, ignore end flags and continue walking the chain even if it appears complete.
withMeta boolean <optional>
 false If true, the SysMeta will be fetched if not already available in the cache.
Since:
  • 2.34.1
Source:
Returns:
- resolves to the previous version PID or an object with { pid, sysMeta } if `withMeta` is true. If no previous version is found, resolves to the original PID.
Type
Promise.<VersionResult>

refresh(pid) → {Promise.<object>}

Refresh the version chain for the given PID by removing it from the cache and re-fetching the full chain from the SysMeta service.
Parameters:
Name Type Description
pid string the PID to refresh
Source:
Returns:
- resolves to the refreshed chain object
Type
Promise.<object>

setTTL(ms)

Set the Time-To-Live (TTL) for cached records.
Parameters:
Name Type Description
ms number the TTL in milliseconds
Source:

getToken() → {Promise.<string>}

Ensure the user is authenticated and has a valid token.
Source:
Returns:
- resolves to the user's token
Type
Promise.<string>