Class: ResourceMapResolver

ResourceMapResolver()

A multi-strategy resource map (RM) look-up tool. Searches for the RM associated with a given PID and allows finding RMs when data packages have not yet been indexed. Tries the following strategies in the order listed: queries index, checks client-side storage, walks the system metadata, and finally guesses the RM PID based on a naming convention. When a match is found, the class stores the Obj-RM PID pair in the client-side storage for future use. When a match is found from a source other than index, the RM is verified to ensure it links to the pid. The history of the resolution attempts is stored in an event log.

Constructor

new ResourceMapResolver()

Since:
  • 2.34.0
Source:

Methods

addToStorage(pid, rm) → {Promise.<(string|null)>}

Adds a resource map PID to the local storage for the given PID.
Parameters:
Name Type Description
pid string The PID of the document to add the RM for
rm string The resource map PID to add
Source:
Returns:
The PID of the resource map added to storage, or null if the addition failed
Type
Promise.<(string|null)>

checkResourceMapMembership(rm, pid, optionsopt) → {Promise.<{isMember: boolean, memberPids: Array.<string>, fetchStatus: number}>}

Fetches a Resource Map and checks whether it contains a PID.
Parameters:
Name Type Attributes Description
rm string The Resource Map PID to fetch
pid string The member PID to check
options object <optional>
 Fetch options
Properties
Name Type Attributes Description
timeoutMs number <optional>
 The maximum time to wait for the fetch
signal AbortSignal <optional>
 Signal used to cancel the fetch
Since:
  • 2.39.0
Source:
Returns:
Membership result and fetch details
Type
Promise.<{isMember: boolean, memberPids: Array.<string>, fetchStatus: number}>

checkStorage(pid) → {Promise.<(string|null)>}

Checks local storage / index DB for a resource map PID associated with the given PID. Uses PersistentStorage to access the local storage.
Parameters:
Name Type Description
pid string The PID of the document to check
Source:
Returns:
The stored RM PID, when present
Type
Promise.<(string|null)>

fetchResourceMap(rm, optionsopt) → {Promise.<{model: (ResourceMap|null), status: number}>}

Fetches and parses the resource map for the given PID.
Parameters:
Name Type Attributes Description
rm string The PID of the resource map to fetch
options object <optional>
 Fetch options
Properties
Name Type Attributes Description
timeoutMs number <optional>
 The maximum time to wait for the fetch.
signal AbortSignal <optional>
 Signal used to cancel the fetch
Source:
Returns:
Parsed resource map and HTTP status.
Type
Promise.<{model: (ResourceMap|null), status: number}>

getPidForSid(sid, optionsopt) → {Promise.<(string|null)>}

Gets the PID for a given series ID (SID) using sys metadata. Ensures that the most recent PID is returned, even if indexing is not complete.
Parameters:
Name Type Attributes Description
sid string The series ID to get the PID for
options object <optional>
 System metadata lookup options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
Source:
Returns:
The PID associated with the series ID, or null if not found
Type
Promise.<(string|null)>

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

Gets the system metadata for a given PID.
Parameters:
Name Type Attributes Description
pid string The PID to get the system metadata for
options object <optional>
 Options to SysMeta service
Since:
  • 2.39.0
Source:
Returns:
The sysMeta for the PID
Type
Promise.<SystemMetadata>

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

Guesses the resource map PID based on the PID. The guessed PID is constructed by appending the PID to a predefined prefix.
Parameters:
Name Type Attributes Description
pid string The PID of the document to guess the RM PID for
options object <optional>
 Verification options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
Source:
Returns:
The guessed resource map PID if it exists and is linked to the PID, null otherwise
Type
Promise.<(string|null)>

log(pid, rm, status, metaopt, levelopt) → {object}

Logs an event for the resolution process.
Parameters:
Name Type Attributes Default Description
pid string The PID of the object being resolved
rm string The resource map PID if found, null otherwise
status string The human-readable status of the resolution
meta object <optional>
 Additional metadata to include in the event
level string <optional>
 info The log level for the event
Source:
Returns:
The event log for the resolution process
Type
object

multiRMCheck(rms, optionsopt) → {Promise.<object>}

When 2 or more resource maps are found in the index for a PID, then this method is called to check if they are all versions of each other. If so, it returns the newest accessible candidate in that version chain. Membership in the requested object's package is checked by `resolve()`.
Parameters:
Name Type Attributes Description
rms Array.<string> An array of resource map PIDs to check
options object <optional>
 Version-chain lookup options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
Since:
  • 2.34.1
Source:
Returns:
The resolved resource map PID, when found, and metadata about the search.
Type
Promise.<object>

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

Collapse a list of PIDs to only the most one for its version chain. For example, if given 3 PIDs that are all part of the same version chain, it will remove the two older versions. If given PIDs that are part of different version chains, it will return the most recent PID from each chain.
Parameters:
Name Type Attributes Description
pids Array.<string> PIDs to group by version chain
options object <optional>
 Version-chain lookup options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
Since:
  • 2.39.0
Source:
Throws:
When resolution is aborted
Type
Error
Returns:
Latest PID from each discovered chain
Type
Promise.<Array.<string>>

resolve(pid, optionsopt, visitedPidsopt) → {Promise.<ResolveResult>}

The main method to resolve the resource map PID for a given PID. It will try multiple strategies in order to find the resource map associated with the PID.
Parameters:
Name Type Attributes Description
pid string The PID of the document to resolve
options object <optional>
 Resolution options.
Properties
Name Type Attributes Description
fields Array.<string> <optional>
 An array of index fields to query in addition to the default fields. This can be used to get additional metadata about the PID from the index to reduce queries by the consumer.
signal AbortSignal <optional>
 Signal used to cancel resolver work
visitedPids Set.<string> <optional>
 PIDs already visited in this path
Source:
Returns:
The result of the resolution process
Type
Promise.<ResolveResult>

resolveFromMetadataPids(metadataPids, optionsopt, visitedPidsopt) → {Promise.<{rm: (string|null), meta: object}>}

Given a list of metadata PIDs, collapse them by version chain, then resolve a resource map for each unique version chain.
Parameters:
Name Type Attributes Description
metadataPids Array.<string> An array of metadata PIDs, e.g. the documentedBy PIDs returned from the index for a data PID.
options object <optional>
 Resolution options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
visitedPids Set.<string> <optional>
 PIDs already visited in this path
Since:
  • 2.39.0
Source:
Returns:
The resolved RM PID if found, and metadata about the resolution attempt
Type
Promise.<{rm: (string|null), meta: object}>

resolveFromSeriesId(sid, optionsopt, visitedPidsopt) → {Promise.<ResolveResult>}

Resolves the resource map PID from a series ID (SID). It first retrieves the system metadata for the series ID to get the most up-to-date PID, then starts the resolution process with the new PID. Called from `resolve` when the index search returns a series ID.
Parameters:
Name Type Attributes Description
sid string The series ID to resolve
options object <optional>
 Resolution options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
visitedPids Set.<string> <optional>
 PIDs already visited in this path
Source:
Returns:
The result of the resolution process
Type
Promise.<ResolveResult>

status(pid, status, rmopt, metaopt) → {ResolveResult}

Records the status of the resolution process for a given PID and triggers Backbone events for the status update.
Parameters:
Name Type Attributes Description
pid string The PID of the object being resolved
status string The human-readable status of the resolution
rm string <optional>
 The resource map PID if found, null otherwise
meta object <optional>
 Additional metadata to include in the status
Source:
Returns:
An object with the result of the resolution
Type
ResolveResult

trackMissingResourceMap(pid)

Track a failed resource map resolution.
Parameters:
Name Type Description
pid string PID whose resource map could not be resolved
Source:

verify(rm, pid, optionsopt) → {Promise.<boolean>}

Verifies that the given resource map PID exists and contains the pid as a member.
Parameters:
Name Type Attributes Description
rm string The PID of the resource map to verify
pid string The PID of the document to check
options object <optional>
 Fetch options
Properties
Name Type Attributes Description
timeoutMs number <optional>
 The maximum time to wait for the fetch.
signal AbortSignal <optional>
 Signal used to cancel the fetch
Source:
Returns:
True if the RM is valid and contains the PID, false otherwise
Type
Promise.<boolean>

walkSysmeta(pid, optionsopt) → {Promise.<{rm: (string|null), meta: object}>}

Walks the system metadata to find the resource map PID associated with the given PID. It starts from the given PID and walks backward through the version history to find an old resource map PID. Then, starting at the found RM pid, walks forward to find the current RM.
Parameters:
Name Type Attributes Description
pid string The PID of the document to walk sysmeta for
options object <optional>
 System metadata lookup options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
Source:
Returns:
An object containing the resource map PID if found, and metadata about the walk
Type
Promise.<{rm: (string|null), meta: object}>

warn(message, erroropt)

Logs a warning message to the event log and console (if console logging is enabled).
Parameters:
Name Type Attributes Description
message string The warning message to log
error Error | object | string <optional>
 An optional error object
Since:
  • 2.39.0
Source:

searchIndex(pid, optionsopt) → {Promise.<(object|null)>}

Searches the index for a resource map associated with the given PID. Returns an object containing the PID and metadata about the search.
Parameters:
Name Type Attributes Description
pid string The PID to search for in the index
options object <optional>
 Search options
Properties
Name Type Attributes Description
fields Array.<string> <optional>
 An array of index fields to query in addition to the default fields.
signal AbortSignal <optional>
 Signal used to cancel the index search.
Source:
Returns:
An object containing the PID and metadata if a resource map is found, null otherwise
Type
Promise.<(object|null)>

ResourceMapResolver(options)

new ResourceMapResolver(options)

Requires `metaServiceUrl` and at least one object-read service URL.
Parameters:
Name Type Description
options object Options for the resolver
Properties
Name Type Attributes Description
metaServiceUrl string The base URL for service to get System Metadata
resolveServiceUrl string <optional>
 Resolve service base URL
objectServiceUrl string <optional>
 Object service base URL
objectService ObjectService <optional>
 Object service used to download Resource Maps
storage PersistentStorage <optional>
 An instance of PersistentStorage to use for storing obj:resMap PID pairs. If not provided, a new instance will be created.
storageOptions PersistentStorage#PersistentStorageOptions <optional>
 Options for creating the PersistentStorage instance if one is not provided. See PersistentStorage#PersistentStorageOptions
eventLog object <optional>
 An instance of EventLog to use for tracing the resolution process. If not provided, a new instance will be created.
maxSteps number <optional>
 The maximum number of steps to walk back in the system metadata to find a resource map PID.
maxFetchTime number <optional>
 The maximum time to wait for fetching the resource map PID from the system metadata. Defaults to 45s.
consoleLevel "info" | "warning" | "error" <optional>
 The level at which to log messages to the console. Defaults to "warning". Set to false to disable console logging.
Source:

Methods

addToStorage(pid, rm) → {Promise.<(string|null)>}

Adds a resource map PID to the local storage for the given PID.
Parameters:
Name Type Description
pid string The PID of the document to add the RM for
rm string The resource map PID to add
Source:
Returns:
The PID of the resource map added to storage, or null if the addition failed
Type
Promise.<(string|null)>

checkResourceMapMembership(rm, pid, optionsopt) → {Promise.<{isMember: boolean, memberPids: Array.<string>, fetchStatus: number}>}

Fetches a Resource Map and checks whether it contains a PID.
Parameters:
Name Type Attributes Description
rm string The Resource Map PID to fetch
pid string The member PID to check
options object <optional>
 Fetch options
Properties
Name Type Attributes Description
timeoutMs number <optional>
 The maximum time to wait for the fetch
signal AbortSignal <optional>
 Signal used to cancel the fetch
Since:
  • 2.39.0
Source:
Returns:
Membership result and fetch details
Type
Promise.<{isMember: boolean, memberPids: Array.<string>, fetchStatus: number}>

checkStorage(pid) → {Promise.<(string|null)>}

Checks local storage / index DB for a resource map PID associated with the given PID. Uses PersistentStorage to access the local storage.
Parameters:
Name Type Description
pid string The PID of the document to check
Source:
Returns:
The stored RM PID, when present
Type
Promise.<(string|null)>

fetchResourceMap(rm, optionsopt) → {Promise.<{model: (ResourceMap|null), status: number}>}

Fetches and parses the resource map for the given PID.
Parameters:
Name Type Attributes Description
rm string The PID of the resource map to fetch
options object <optional>
 Fetch options
Properties
Name Type Attributes Description
timeoutMs number <optional>
 The maximum time to wait for the fetch.
signal AbortSignal <optional>
 Signal used to cancel the fetch
Source:
Returns:
Parsed resource map and HTTP status.
Type
Promise.<{model: (ResourceMap|null), status: number}>

getPidForSid(sid, optionsopt) → {Promise.<(string|null)>}

Gets the PID for a given series ID (SID) using sys metadata. Ensures that the most recent PID is returned, even if indexing is not complete.
Parameters:
Name Type Attributes Description
sid string The series ID to get the PID for
options object <optional>
 System metadata lookup options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
Source:
Returns:
The PID associated with the series ID, or null if not found
Type
Promise.<(string|null)>

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

Gets the system metadata for a given PID.
Parameters:
Name Type Attributes Description
pid string The PID to get the system metadata for
options object <optional>
 Options to SysMeta service
Since:
  • 2.39.0
Source:
Returns:
The sysMeta for the PID
Type
Promise.<SystemMetadata>

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

Guesses the resource map PID based on the PID. The guessed PID is constructed by appending the PID to a predefined prefix.
Parameters:
Name Type Attributes Description
pid string The PID of the document to guess the RM PID for
options object <optional>
 Verification options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
Source:
Returns:
The guessed resource map PID if it exists and is linked to the PID, null otherwise
Type
Promise.<(string|null)>

log(pid, rm, status, metaopt, levelopt) → {object}

Logs an event for the resolution process.
Parameters:
Name Type Attributes Default Description
pid string The PID of the object being resolved
rm string The resource map PID if found, null otherwise
status string The human-readable status of the resolution
meta object <optional>
 Additional metadata to include in the event
level string <optional>
 info The log level for the event
Source:
Returns:
The event log for the resolution process
Type
object

multiRMCheck(rms, optionsopt) → {Promise.<object>}

When 2 or more resource maps are found in the index for a PID, then this method is called to check if they are all versions of each other. If so, it returns the newest accessible candidate in that version chain. Membership in the requested object's package is checked by `resolve()`.
Parameters:
Name Type Attributes Description
rms Array.<string> An array of resource map PIDs to check
options object <optional>
 Version-chain lookup options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
Since:
  • 2.34.1
Source:
Returns:
The resolved resource map PID, when found, and metadata about the search.
Type
Promise.<object>

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

Collapse a list of PIDs to only the most one for its version chain. For example, if given 3 PIDs that are all part of the same version chain, it will remove the two older versions. If given PIDs that are part of different version chains, it will return the most recent PID from each chain.
Parameters:
Name Type Attributes Description
pids Array.<string> PIDs to group by version chain
options object <optional>
 Version-chain lookup options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
Since:
  • 2.39.0
Source:
Throws:
When resolution is aborted
Type
Error
Returns:
Latest PID from each discovered chain
Type
Promise.<Array.<string>>

resolve(pid, optionsopt, visitedPidsopt) → {Promise.<ResolveResult>}

The main method to resolve the resource map PID for a given PID. It will try multiple strategies in order to find the resource map associated with the PID.
Parameters:
Name Type Attributes Description
pid string The PID of the document to resolve
options object <optional>
 Resolution options.
Properties
Name Type Attributes Description
fields Array.<string> <optional>
 An array of index fields to query in addition to the default fields. This can be used to get additional metadata about the PID from the index to reduce queries by the consumer.
signal AbortSignal <optional>
 Signal used to cancel resolver work
visitedPids Set.<string> <optional>
 PIDs already visited in this path
Source:
Returns:
The result of the resolution process
Type
Promise.<ResolveResult>

resolveFromMetadataPids(metadataPids, optionsopt, visitedPidsopt) → {Promise.<{rm: (string|null), meta: object}>}

Given a list of metadata PIDs, collapse them by version chain, then resolve a resource map for each unique version chain.
Parameters:
Name Type Attributes Description
metadataPids Array.<string> An array of metadata PIDs, e.g. the documentedBy PIDs returned from the index for a data PID.
options object <optional>
 Resolution options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
visitedPids Set.<string> <optional>
 PIDs already visited in this path
Since:
  • 2.39.0
Source:
Returns:
The resolved RM PID if found, and metadata about the resolution attempt
Type
Promise.<{rm: (string|null), meta: object}>

resolveFromSeriesId(sid, optionsopt, visitedPidsopt) → {Promise.<ResolveResult>}

Resolves the resource map PID from a series ID (SID). It first retrieves the system metadata for the series ID to get the most up-to-date PID, then starts the resolution process with the new PID. Called from `resolve` when the index search returns a series ID.
Parameters:
Name Type Attributes Description
sid string The series ID to resolve
options object <optional>
 Resolution options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
visitedPids Set.<string> <optional>
 PIDs already visited in this path
Source:
Returns:
The result of the resolution process
Type
Promise.<ResolveResult>

status(pid, status, rmopt, metaopt) → {ResolveResult}

Records the status of the resolution process for a given PID and triggers Backbone events for the status update.
Parameters:
Name Type Attributes Description
pid string The PID of the object being resolved
status string The human-readable status of the resolution
rm string <optional>
 The resource map PID if found, null otherwise
meta object <optional>
 Additional metadata to include in the status
Source:
Returns:
An object with the result of the resolution
Type
ResolveResult

trackMissingResourceMap(pid)

Track a failed resource map resolution.
Parameters:
Name Type Description
pid string PID whose resource map could not be resolved
Source:

verify(rm, pid, optionsopt) → {Promise.<boolean>}

Verifies that the given resource map PID exists and contains the pid as a member.
Parameters:
Name Type Attributes Description
rm string The PID of the resource map to verify
pid string The PID of the document to check
options object <optional>
 Fetch options
Properties
Name Type Attributes Description
timeoutMs number <optional>
 The maximum time to wait for the fetch.
signal AbortSignal <optional>
 Signal used to cancel the fetch
Source:
Returns:
True if the RM is valid and contains the PID, false otherwise
Type
Promise.<boolean>

walkSysmeta(pid, optionsopt) → {Promise.<{rm: (string|null), meta: object}>}

Walks the system metadata to find the resource map PID associated with the given PID. It starts from the given PID and walks backward through the version history to find an old resource map PID. Then, starting at the found RM pid, walks forward to find the current RM.
Parameters:
Name Type Attributes Description
pid string The PID of the document to walk sysmeta for
options object <optional>
 System metadata lookup options
Properties
Name Type Attributes Description
signal AbortSignal <optional>
 Signal used to cancel resolver work
Source:
Returns:
An object containing the resource map PID if found, and metadata about the walk
Type
Promise.<{rm: (string|null), meta: object}>

warn(message, erroropt)

Logs a warning message to the event log and console (if console logging is enabled).
Parameters:
Name Type Attributes Description
message string The warning message to log
error Error | object | string <optional>
 An optional error object
Since:
  • 2.39.0
Source:

searchIndex(pid, optionsopt) → {Promise.<(object|null)>}

Searches the index for a resource map associated with the given PID. Returns an object containing the PID and metadata about the search.
Parameters:
Name Type Attributes Description
pid string The PID to search for in the index
options object <optional>
 Search options
Properties
Name Type Attributes Description
fields Array.<string> <optional>
 An array of index fields to query in addition to the default fields.
signal AbortSignal <optional>
 Signal used to cancel the index search.
Source:
Returns:
An object containing the PID and metadata if a resource map is found, null otherwise
Type
Promise.<(object|null)>