Class: DataONEService

DataONEService()

new DataONEService()

Extensible base class for DataONE API services, e.g. the System Metadata service. It includes in-memory and persistent caching scoped by user authentication, deduplication of in-flight requests handled by the DataONEHttpClient, and utility methods for making requests. This class always uses singleton instances of DataONEHttpClient and PersistentStorage to ensure that deduplication and caching work properly across all service instances with the same configuration. Subclasses describe themselves with a static DataONEService.config descriptor (endpoint name, the AppModel URL keys used to resolve a base URL, default HTTP client options, storage defaults, and auth defaults). The base class turns that descriptor into the constructor options via DataONEService.optionsFromDescriptor, so most subclasses only need a one-line constructor plus their domain methods.
Since:
  • 2.39.0
Source:

Members

endpoint

Source:

serviceName

Source:

Methods

clearCache() → {Promise.<void>}

Clear the cache for the current user scope.
Source:
Returns:
Promise resolving when the cache is cleared
Type
Promise.<void>

download(path, optionsopt) → {Promise.<*>}

Download data from a path with optional caching.
Parameters:
Name Type Attributes Description
path string Path relative to baseUrl
options object <optional>
 Options passed to DataONEHttpClient#request (except `path`), plus cache controls.
Properties
Name Type Attributes Description
auth boolean <optional>
 Whether to resolve a token automatically
useCache boolean <optional>
 Whether to cache responses, default true.
cacheKey string <optional>
 Cache key override
cacheTtlMs number | null <optional>
 Cache TTL override
Source:
Returns:
Promise resolving to response data
Type
Promise.<*>

getCached(key) → {Promise.<*>}

Get a cached value scoped by the current user.
Parameters:
Name Type Description
key string Cache key
Source:
Returns:
Promise resolving to the cached value
Type
Promise.<*>

getStore() → {PersistentStorage}

Get a PersistentStorage instance automatically scoped by the logged in user, using the configuration options provided to the constructor.
Source:
Returns:
Storage instance
Type
PersistentStorage

getToken() → {Promise.<string>}

Resolve an auth token from MetacatUI when available.
Source:
Returns:
Promise resolving to an auth token
Type
Promise.<string>

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

Resolve the current username from the MetacatUI app user model.
Source:
Returns:
Promise resolving to the username, or null if unavailable.
Type
Promise.<(string|null)>

isCached(key) → {Promise.<boolean>}

Check whether a value exists in the cache for the current user scope.
Parameters:
Name Type Description
key string Cache key
Source:
Returns:
Promise resolving to whether the value is cached.
Type
Promise.<boolean>

removeCached(key) → {Promise.<void>}

Remove a cached value for the current user scope.
Parameters:
Name Type Description
key string Cache key
Source:
Returns:
Promise resolving when removal completes
Type
Promise.<void>

request(optionsopt) → {Promise.<DataONEHttpResponse>}

Send a request via the DataONEHttpClient.
Parameters:
Name Type Attributes Description
options object <optional>
 Request options passed to DataONEHttpClient#request, plus auth controls.
Properties
Name Type Attributes Description
path string Path relative to baseUrl
auth boolean <optional>
 Whether to resolve a token automatically
Source:
Returns:
Promise resolving to the response.
Type
Promise.<DataONEHttpResponse>

requestWithClient(client, optionsopt) → {Promise.<DataONEHttpResponse>}

Send a request through a specific DataONEHttpClient instance.
Parameters:
Name Type Attributes Description
client DataONEHttpClient Client instance to use
options object <optional>
 Request options
Source:
Throws:
When client is invalid or the request fails
Type
Error
Returns:
Promise resolving to the response.
Type
Promise.<DataONEHttpResponse>

resolveToken(authopt) → {Promise.<(string|null)>}

Determine the token to use, if any, for a request.
Parameters:
Name Type Attributes Description
auth boolean <optional>
 Whether to use authentication for this request If set to false, no token will be used. If true, getToken() will be called. When undefined, defaultAuth is used.
Source:
Returns:
Promise resolving to the token, or null if no auth.
Type
Promise.<(string|null)>

scopeKey() → {Promise.<string>}

If user is logged in, get a key based on their username; otherwise, return a "public" scope key.
Source:
Returns:
Promise resolving to the scope key
Type
Promise.<string>

sendParsedIdentifierRequest(params) → {Promise.<DataONEHttpResponse>}

Send a request whose body is a DataONE identifier response and parse the returned XML. Shared by services that POST/PUT and read back an identifier (e.g. IdentifierService, ObjectService).
Parameters:
Name Type Description
params object Request params
Properties
Name Type Attributes Description
client DataONEHttpClient <optional>
 Client to use. Defaults to the service's primary client when omitted.
requestOptions object Options from DataONEService.buildRequestOptions.
context string Error/parse context label
Source:
Throws:
When the request or identifier parsing fails
Type
Error
Returns:
Response with parsed identifier data.
Type
Promise.<DataONEHttpResponse>

setCached(key, value, optionsopt) → {Promise.<*>}

Store a value in the cache for the current user scope.
Parameters:
Name Type Attributes Description
key string Cache key
value * Value to store
options object <optional>
 Cache scope options
Properties
Name Type Attributes Description
ttlMs number | null <optional>
 Override cache TTL in ms
Source:
Returns:
Promise resolving to the stored value
Type
Promise.<*>

shouldUseCache() → {Promise.<boolean>}

Determine whether caching is allowed for the current user scope.
Source:
Returns:
Promise resolving to whether caching is allowed.
Type
Promise.<boolean>

upload(path, optionsopt) → {Promise.<DataONEHttpResponse>}

Upload data to a path.
Parameters:
Name Type Attributes Description
path string Path relative to baseUrl
options object <optional>
 Options passed to DataONEHttpClient#request (except `path`), plus cache controls.
Properties
Name Type Attributes Description
auth boolean <optional>
 Whether to resolve a token automatically
cacheKey string <optional>
 Cache key override
Source:
Returns:
Promise resolving to the response.
Type
Promise.<DataONEHttpResponse>

awaitUserModel() → {Promise.<Backbone.Model>}

Wait for the MetacatUI app user model to be available, and return it.
Source:
Returns:
Promise resolving to the user model
Type
Promise.<Backbone.Model>

buildClientConfig(paramsopt) → {object}

Merge default and caller-provided client options. The method, response type, and dedupe-header lists are merged as a union (defaults are always preserved; overrides can only add), so service defaults double as the required set and never need to be re-declared.
Parameters:
Name Type Attributes Description
params object <optional>
 Client configuration params
Properties
Name Type Attributes Description
defaults object <optional>
 Default client options
overrides object <optional>
 Caller-provided client options
baseUrl string <optional>
 Base URL for the client
Source:
Returns:
Normalized client configuration
Type
object

buildPidPath(pid, optionsopt) → {string}

Build a request path from a PID, encoded as a single path segment, with an optional query string. Always pair with `encodePath: false`.
Parameters:
Name Type Attributes Description
pid * Candidate identifier
options object <optional>
 Path options
Properties
Name Type Attributes Description
query string <optional>
 Query string appended after `?`
Source:
Throws:
When pid is empty
Type
Error
Returns:
Encoded PID path
Type
string

buildRequestOptions(params) → {object}

Build normalized request options for a single DataONE call. Centralizes the option-picking, default Accept header, path encoding, and the common `responseType`/`dedupe`/`auth`/`body` wiring shared by the services.
Parameters:
Name Type Description
params object Request params
Properties
Name Type Attributes Description
options object <optional>
 Caller request options to forward
path string Path relative to baseUrl
method string HTTP method
accept string <optional>
 Default Accept header value
responseType string <optional>
 Response type, defaults to `text`
body * <optional>
 Request body
dedupe boolean <optional>
 Dedupe override
auth boolean <optional>
 Auth override
encodePath boolean <optional>
 Whether the client should re-encode the path. Defaults to false because callers pass pre-encoded PID paths.
extra object <optional>
 Additional request options to merge in, e.g. `transport`.
Source:
Returns:
Normalized request options
Type
object

buildStorageConfig(callerStorageConfigopt, baseUrl) → {object}

Build a PersistentStorage config namespaced by service name and base URL.
Parameters:
Name Type Attributes Description
callerStorageConfig object <optional>
 Caller-provided storage options
baseUrl string Resolved base URL
Source:
Returns:
Storage config with namespaced instance keys
Type
object

clientDefaults() → {object}

Translate the friendly DataONEServiceConfig `client` block into DataONEHttpClient option names.
Source:
Returns:
Default client options for buildClientConfig
Type
object

encodePidPath(pid, labelopt, messageopt) → {string}

Encode a PID as a single URL path segment.
Parameters:
Name Type Attributes Default Description
pid * Candidate identifier
label string <optional>
 pid Field label for error reporting
message string <optional>
 Error message override
Source:
Throws:
When pid is empty
Type
Error
Returns:
Encoded PID path segment
Type
string

isAmbiguousWriteError(error) → {boolean}

Whether a DataONE write failure may have committed remotely.
Parameters:
Name Type Description
error Error | object Service error
Source:
Returns:
True when the write result must be verified
Type
boolean

mergeHeadersWithDefaults(requestHeadersopt, defaultHeadersopt) → {object}

Merge request headers with defaults case-insensitively. Caller-provided headers always win, while preserving caller casing.
Parameters:
Name Type Attributes Description
requestHeaders object <optional>
 Headers for the request
defaultHeaders object <optional>
 Default headers to apply when missing
Source:
Returns:
Merged headers
Type
object

normalizeOptions(options) → {object}

Normalize the options used to construct a new instance.
Parameters:
Name Type Description
options object Options passed to the constructor
Source:
Returns:
Normalized options
Type
object

normalizePid(pid, labelopt, messageopt) → {string}

Normalize and validate a PID-like identifier.
Parameters:
Name Type Attributes Default Description
pid * Candidate identifier
label string <optional>
 pid Field label for error reporting
message string <optional>
 Error message override
Source:
Throws:
When pid is empty
Type
Error
Returns:
Trimmed PID
Type
string

optionsFromDescriptor(optionsopt) → {object}

Build DataONEService constructor options from the static descriptor and caller options. Subclasses pass the result to `super()`.
Parameters:
Name Type Attributes Description
options object <optional>
 Caller-provided service options
Source:
Throws:
When no base URL can be resolved
Type
Error
Returns:
Normalized constructor options
Type
object

pickRequestOptions(optionsopt, keysopt) → {object}

Pick defined request options from a candidate options object.
Parameters:
Name Type Attributes Description
options object <optional>
 Candidate options
keys Array.<string> <optional>
 Keys to retain when defined
Source:
Returns:
Selected options
Type
object

resolveBaseUrl(explicitBaseUrlopt) → {string}

Resolve a base URL from an explicit value, then the descriptor's `appModelKeys` in order. Subclasses with composite URLs override this.
Parameters:
Name Type Attributes Description
explicitBaseUrl string <optional>
 Caller-provided base URL
Source:
Returns:
Normalized base URL, or an empty string when unresolved
Type
string

resolveCacheKey(path, cacheKeyopt) → {string}

Use the path as the cache key by default, but allow an override if desired.
Parameters:
Name Type Attributes Description
path string Path relative to baseUrl
cacheKey string | null | undefined <optional>
 Cache key override
Source:
Returns:
Resolved cache key
Type
string

withDefaultAccept(optionsopt, acceptopt) → {object}

Apply a default Accept header when one is not already provided.
Parameters:
Name Type Attributes Default Description
options object <optional>
 Request options
accept string <optional>
 text/xml Default Accept header value
Source:
Returns:
Options object with merged headers
Type
object

DataONEService(optionsopt)

new DataONEService(optionsopt)

Parameters:
Name Type Attributes Description
options object <optional>
 Options for the service instance
Properties
Name Type Attributes Description
baseUrl string Base URL for the DataONE endpoint, e.g https://cn.dataone.org/cn/v2
clientConfig DataONEHttpClient#DataONEHttpClientOptions <optional>
 DataONEHttpClient options
storageConfig PersistentStorage#PersistentStorageOptions <optional>
 Storage options, plus DataONEService namespace fields (e.g. `domain`, `endpoint`, `app`, `scope`, `baseUrl`).
persistPrivate boolean <optional>
 Whether or not to persist private (authenticated) data in storage. Defaults to false.
getToken function <optional>
 A function that returns a Promise that resolves to an auth token string.
getUserName function <optional>
 A function that returns a Promise that resolves to the current username string, used by cache-scoped services.
defaultAuth boolean <optional>
 Whether or not to send requests with authorization by default, when no auth option is provided, and when a user token is available. Defaults to true.
Source:

Members

endpoint

Source:

serviceName

Source:

Methods

clearCache() → {Promise.<void>}

Clear the cache for the current user scope.
Source:
Returns:
Promise resolving when the cache is cleared
Type
Promise.<void>

download(path, optionsopt) → {Promise.<*>}

Download data from a path with optional caching.
Parameters:
Name Type Attributes Description
path string Path relative to baseUrl
options object <optional>
 Options passed to DataONEHttpClient#request (except `path`), plus cache controls.
Properties
Name Type Attributes Description
auth boolean <optional>
 Whether to resolve a token automatically
useCache boolean <optional>
 Whether to cache responses, default true.
cacheKey string <optional>
 Cache key override
cacheTtlMs number | null <optional>
 Cache TTL override
Source:
Returns:
Promise resolving to response data
Type
Promise.<*>

getCached(key) → {Promise.<*>}

Get a cached value scoped by the current user.
Parameters:
Name Type Description
key string Cache key
Source:
Returns:
Promise resolving to the cached value
Type
Promise.<*>

getStore() → {PersistentStorage}

Get a PersistentStorage instance automatically scoped by the logged in user, using the configuration options provided to the constructor.
Source:
Returns:
Storage instance
Type
PersistentStorage

getToken() → {Promise.<string>}

Resolve an auth token from MetacatUI when available.
Source:
Returns:
Promise resolving to an auth token
Type
Promise.<string>

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

Resolve the current username from the MetacatUI app user model.
Source:
Returns:
Promise resolving to the username, or null if unavailable.
Type
Promise.<(string|null)>

isCached(key) → {Promise.<boolean>}

Check whether a value exists in the cache for the current user scope.
Parameters:
Name Type Description
key string Cache key
Source:
Returns:
Promise resolving to whether the value is cached.
Type
Promise.<boolean>

removeCached(key) → {Promise.<void>}

Remove a cached value for the current user scope.
Parameters:
Name Type Description
key string Cache key
Source:
Returns:
Promise resolving when removal completes
Type
Promise.<void>

request(optionsopt) → {Promise.<DataONEHttpResponse>}

Send a request via the DataONEHttpClient.
Parameters:
Name Type Attributes Description
options object <optional>
 Request options passed to DataONEHttpClient#request, plus auth controls.
Properties
Name Type Attributes Description
path string Path relative to baseUrl
auth boolean <optional>
 Whether to resolve a token automatically
Source:
Returns:
Promise resolving to the response.
Type
Promise.<DataONEHttpResponse>

requestWithClient(client, optionsopt) → {Promise.<DataONEHttpResponse>}

Send a request through a specific DataONEHttpClient instance.
Parameters:
Name Type Attributes Description
client DataONEHttpClient Client instance to use
options object <optional>
 Request options
Source:
Throws:
When client is invalid or the request fails
Type
Error
Returns:
Promise resolving to the response.
Type
Promise.<DataONEHttpResponse>

resolveToken(authopt) → {Promise.<(string|null)>}

Determine the token to use, if any, for a request.
Parameters:
Name Type Attributes Description
auth boolean <optional>
 Whether to use authentication for this request If set to false, no token will be used. If true, getToken() will be called. When undefined, defaultAuth is used.
Source:
Returns:
Promise resolving to the token, or null if no auth.
Type
Promise.<(string|null)>

scopeKey() → {Promise.<string>}

If user is logged in, get a key based on their username; otherwise, return a "public" scope key.
Source:
Returns:
Promise resolving to the scope key
Type
Promise.<string>

sendParsedIdentifierRequest(params) → {Promise.<DataONEHttpResponse>}

Send a request whose body is a DataONE identifier response and parse the returned XML. Shared by services that POST/PUT and read back an identifier (e.g. IdentifierService, ObjectService).
Parameters:
Name Type Description
params object Request params
Properties
Name Type Attributes Description
client DataONEHttpClient <optional>
 Client to use. Defaults to the service's primary client when omitted.
requestOptions object Options from DataONEService.buildRequestOptions.
context string Error/parse context label
Source:
Throws:
When the request or identifier parsing fails
Type
Error
Returns:
Response with parsed identifier data.
Type
Promise.<DataONEHttpResponse>

setCached(key, value, optionsopt) → {Promise.<*>}

Store a value in the cache for the current user scope.
Parameters:
Name Type Attributes Description
key string Cache key
value * Value to store
options object <optional>
 Cache scope options
Properties
Name Type Attributes Description
ttlMs number | null <optional>
 Override cache TTL in ms
Source:
Returns:
Promise resolving to the stored value
Type
Promise.<*>

shouldUseCache() → {Promise.<boolean>}

Determine whether caching is allowed for the current user scope.
Source:
Returns:
Promise resolving to whether caching is allowed.
Type
Promise.<boolean>

upload(path, optionsopt) → {Promise.<DataONEHttpResponse>}

Upload data to a path.
Parameters:
Name Type Attributes Description
path string Path relative to baseUrl
options object <optional>
 Options passed to DataONEHttpClient#request (except `path`), plus cache controls.
Properties
Name Type Attributes Description
auth boolean <optional>
 Whether to resolve a token automatically
cacheKey string <optional>
 Cache key override
Source:
Returns:
Promise resolving to the response.
Type
Promise.<DataONEHttpResponse>

awaitUserModel() → {Promise.<Backbone.Model>}

Wait for the MetacatUI app user model to be available, and return it.
Source:
Returns:
Promise resolving to the user model
Type
Promise.<Backbone.Model>

buildClientConfig(paramsopt) → {object}

Merge default and caller-provided client options. The method, response type, and dedupe-header lists are merged as a union (defaults are always preserved; overrides can only add), so service defaults double as the required set and never need to be re-declared.
Parameters:
Name Type Attributes Description
params object <optional>
 Client configuration params
Properties
Name Type Attributes Description
defaults object <optional>
 Default client options
overrides object <optional>
 Caller-provided client options
baseUrl string <optional>
 Base URL for the client
Source:
Returns:
Normalized client configuration
Type
object

buildPidPath(pid, optionsopt) → {string}

Build a request path from a PID, encoded as a single path segment, with an optional query string. Always pair with `encodePath: false`.
Parameters:
Name Type Attributes Description
pid * Candidate identifier
options object <optional>
 Path options
Properties
Name Type Attributes Description
query string <optional>
 Query string appended after `?`
Source:
Throws:
When pid is empty
Type
Error
Returns:
Encoded PID path
Type
string

buildRequestOptions(params) → {object}

Build normalized request options for a single DataONE call. Centralizes the option-picking, default Accept header, path encoding, and the common `responseType`/`dedupe`/`auth`/`body` wiring shared by the services.
Parameters:
Name Type Description
params object Request params
Properties
Name Type Attributes Description
options object <optional>
 Caller request options to forward
path string Path relative to baseUrl
method string HTTP method
accept string <optional>
 Default Accept header value
responseType string <optional>
 Response type, defaults to `text`
body * <optional>
 Request body
dedupe boolean <optional>
 Dedupe override
auth boolean <optional>
 Auth override
encodePath boolean <optional>
 Whether the client should re-encode the path. Defaults to false because callers pass pre-encoded PID paths.
extra object <optional>
 Additional request options to merge in, e.g. `transport`.
Source:
Returns:
Normalized request options
Type
object

buildStorageConfig(callerStorageConfigopt, baseUrl) → {object}

Build a PersistentStorage config namespaced by service name and base URL.
Parameters:
Name Type Attributes Description
callerStorageConfig object <optional>
 Caller-provided storage options
baseUrl string Resolved base URL
Source:
Returns:
Storage config with namespaced instance keys
Type
object

clientDefaults() → {object}

Translate the friendly DataONEServiceConfig `client` block into DataONEHttpClient option names.
Source:
Returns:
Default client options for buildClientConfig
Type
object

encodePidPath(pid, labelopt, messageopt) → {string}

Encode a PID as a single URL path segment.
Parameters:
Name Type Attributes Default Description
pid * Candidate identifier
label string <optional>
 pid Field label for error reporting
message string <optional>
 Error message override
Source:
Throws:
When pid is empty
Type
Error
Returns:
Encoded PID path segment
Type
string

isAmbiguousWriteError(error) → {boolean}

Whether a DataONE write failure may have committed remotely.
Parameters:
Name Type Description
error Error | object Service error
Source:
Returns:
True when the write result must be verified
Type
boolean

mergeHeadersWithDefaults(requestHeadersopt, defaultHeadersopt) → {object}

Merge request headers with defaults case-insensitively. Caller-provided headers always win, while preserving caller casing.
Parameters:
Name Type Attributes Description
requestHeaders object <optional>
 Headers for the request
defaultHeaders object <optional>
 Default headers to apply when missing
Source:
Returns:
Merged headers
Type
object

normalizeOptions(options) → {object}

Normalize the options used to construct a new instance.
Parameters:
Name Type Description
options object Options passed to the constructor
Source:
Returns:
Normalized options
Type
object

normalizePid(pid, labelopt, messageopt) → {string}

Normalize and validate a PID-like identifier.
Parameters:
Name Type Attributes Default Description
pid * Candidate identifier
label string <optional>
 pid Field label for error reporting
message string <optional>
 Error message override
Source:
Throws:
When pid is empty
Type
Error
Returns:
Trimmed PID
Type
string

optionsFromDescriptor(optionsopt) → {object}

Build DataONEService constructor options from the static descriptor and caller options. Subclasses pass the result to `super()`.
Parameters:
Name Type Attributes Description
options object <optional>
 Caller-provided service options
Source:
Throws:
When no base URL can be resolved
Type
Error
Returns:
Normalized constructor options
Type
object

pickRequestOptions(optionsopt, keysopt) → {object}

Pick defined request options from a candidate options object.
Parameters:
Name Type Attributes Description
options object <optional>
 Candidate options
keys Array.<string> <optional>
 Keys to retain when defined
Source:
Returns:
Selected options
Type
object

resolveBaseUrl(explicitBaseUrlopt) → {string}

Resolve a base URL from an explicit value, then the descriptor's `appModelKeys` in order. Subclasses with composite URLs override this.
Parameters:
Name Type Attributes Description
explicitBaseUrl string <optional>
 Caller-provided base URL
Source:
Returns:
Normalized base URL, or an empty string when unresolved
Type
string

resolveCacheKey(path, cacheKeyopt) → {string}

Use the path as the cache key by default, but allow an override if desired.
Parameters:
Name Type Attributes Description
path string Path relative to baseUrl
cacheKey string | null | undefined <optional>
 Cache key override
Source:
Returns:
Resolved cache key
Type
string

withDefaultAccept(optionsopt, acceptopt) → {object}

Apply a default Accept header when one is not already provided.
Parameters:
Name Type Attributes Default Description
options object <optional>
 Request options
accept string <optional>
 text/xml Default Accept header value
Source:
Returns:
Options object with merged headers
Type
object