Class: ObjectService

ObjectService()

new ObjectService()

Service for DataONE object read/download/create/update operations.
Since:
  • 2.39.0
Source:

Extends

Methods

buildTransferRequest(path, method, body, optionsopt) → {object}

Build request options for create/update transfer requests.
Parameters:
Name Type Attributes Description
path string Request path.
method "POST" | "PUT" HTTP method.
body FormData Multipart payload.
options object <optional>
 Transfer options.
Source:
Returns:
Normalized request options.
Type
object

clearCache() → {Promise.<void>}

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

create(params, optionsopt) → {Promise.<DataONEHttpResponse>}

Create a new DataONE object.
Parameters:
Name Type Attributes Description
params object Creation params.
Properties
Name Type Attributes Description
pid string PID for the new object.
object * Object payload.
sysMetaXml string System metadata XML.
fileName string <optional>
 Optional filename.
options object <optional>
 Transfer options.
Source:
Throws:
When required params are missing or the request fails
Type
Error
Returns:
Upload response.
Type
Promise.<DataONEHttpResponse>

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

Download object content and return only the response data.
Parameters:
Name Type Attributes Description
pid string PID to download.
options object <optional>
 Request options for ObjectService#fetch.
Overrides:
Source:
Returns:
Response payload.
Type
Promise.<*>

downloadFromWriteTarget(pid, optionsopt) → {Promise.<*>}

Download object content from the repository that accepts writes.
Parameters:
Name Type Attributes Description
pid string PID to download
options object <optional>
 Request options
Source:
Returns:
Response payload
Type
Promise.<*>

fetch(pid, optionsopt) → {Promise.<DataONEHttpResponse>}

Fetch object content and return the full normalized response.
Parameters:
Name Type Attributes Description
pid string PID to fetch.
options object <optional>
 Request options for DataONEService#request.
Source:
Returns:
Full response object.
Type
Promise.<DataONEHttpResponse>

fetchFromLocations(objectServiceUrls, request, token) → {Promise.<DataONEHttpResponse>}

Fetch an object from its registered locations.
Parameters:
Name Type Description
objectServiceUrls Array.<string> Registered object service URLs
request object Built request options
token string Bearer token
Since:
  • 2.39.0
Source:
Returns:
Full response object
Type
Promise.<DataONEHttpResponse>

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

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

getReadClient(baseUrl) → {DataONEHttpClient}

Get a read client for a selected object service URL.
Parameters:
Name Type Description
baseUrl string Object service base URL
Since:
  • 2.39.0
Source:
Returns:
Read client instance
Type
DataONEHttpClient

getReadUrl(pid) → {string}

Build the exact request URL used to read an object.
Parameters:
Name Type Description
pid string PID to read.
Source:
Returns:
Full object request URL.
Type
string

getStore() → {PersistentStorage}

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

getToken() → {Promise.<string>}

Resolve an auth token from MetacatUI when available.
Inherited From:
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.
Inherited From:
Source:
Returns:
Promise resolving to the username, or null if unavailable.
Type
Promise.<(string|null)>

getWriteClient(operation) → {DataONEHttpClient}

Get the write client for create/update requests.
Parameters:
Name Type Description
operation string Operation name for error reporting.
Source:
Throws:
When writeBaseUrl is missing
Type
Error
Returns:
Write client instance.
Type
DataONEHttpClient

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
Inherited From:
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
Inherited From:
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
Inherited From:
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
Inherited From:
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.
Inherited From:
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.
Inherited From:
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
Inherited From:
Source:
Throws:
When the request or identifier parsing fails
Type
Error
Returns:
Response with parsed identifier data.
Type
Promise.<DataONEHttpResponse>

sendTransferRequest(operation, path, method, body, context, optionsopt) → {Promise.<DataONEHttpResponse>}

Execute a create/update transfer request and normalize the XML response.
Parameters:
Name Type Attributes Description
operation string Operation name for error reporting.
path string Request path.
method "POST" | "PUT" HTTP method.
body FormData Multipart payload.
context string Error/parse context.
options object <optional>
 Transfer options.
Source:
Returns:
Parsed identifier response.
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
Inherited From:
Source:
Returns:
Promise resolving to the stored value
Type
Promise.<*>

shouldUseCache() → {Promise.<boolean>}

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

update(params, optionsopt) → {Promise.<DataONEHttpResponse>}

Update an existing DataONE object.
Parameters:
Name Type Attributes Description
params object Update params.
Properties
Name Type Attributes Description
pid string Existing (old) PID.
newPid string Replacement PID.
object * Updated object payload.
sysMetaXml string Updated system metadata XML.
fileName string <optional>
 Optional filename.
options object <optional>
 Transfer options.
Source:
Throws:
When required params are missing or the request fails
Type
Error
Returns:
Update response.
Type
Promise.<DataONEHttpResponse>

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
Inherited From:
Source:
Returns:
Promise resolving to the response.
Type
Promise.<DataONEHttpResponse>

appendObjectBody(formData, objectBody, fileNameopt)

Append object content to multipart form data.
Parameters:
Name Type Attributes Description
formData FormData FormData instance.
objectBody * Object content.
fileName string <optional>
 Optional file name.
Source:

buildTransferFormData(params) → {FormData}

Build the multipart form data for create/update requests.
Parameters:
Name Type Description
params object Transfer params.
Properties
Name Type Attributes Description
pid string Existing or new PID.
newPid string <optional>
 Replacement PID for updates.
object * Object payload.
sysMetaXml string System metadata XML.
fileName string <optional>
 Optional filename.
Source:
Returns:
Multipart form data.
Type
FormData

ObjectService(optionsopt)

new ObjectService(optionsopt)

Parameters:
Name Type Attributes Description
options object <optional>
 Options for the ObjectService
Properties
Name Type Attributes Description
readBaseUrl string <optional>
 Base URL for object reads
writeBaseUrl string <optional>
 Base URL for object writes
resolveServiceUrl string <optional>
 CN resolve service URL
metaServiceUrl string <optional>
 System Metadata service URL
locationResolver ObjectLocationResolver <optional>
 Object location resolver
clientConfig DataONEHttpClient#DataONEHttpClientOptions <optional>
 DataONEHttpClient configuration
defaultAuth boolean <optional>
 Default auth behavior
getToken function <optional>
 Override token resolver function
Source:
Throws:
When readBaseUrl is missing
Type
Error

Methods

buildTransferRequest(path, method, body, optionsopt) → {object}

Build request options for create/update transfer requests.
Parameters:
Name Type Attributes Description
path string Request path.
method "POST" | "PUT" HTTP method.
body FormData Multipart payload.
options object <optional>
 Transfer options.
Source:
Returns:
Normalized request options.
Type
object

clearCache() → {Promise.<void>}

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

create(params, optionsopt) → {Promise.<DataONEHttpResponse>}

Create a new DataONE object.
Parameters:
Name Type Attributes Description
params object Creation params.
Properties
Name Type Attributes Description
pid string PID for the new object.
object * Object payload.
sysMetaXml string System metadata XML.
fileName string <optional>
 Optional filename.
options object <optional>
 Transfer options.
Source:
Throws:
When required params are missing or the request fails
Type
Error
Returns:
Upload response.
Type
Promise.<DataONEHttpResponse>

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

Download object content and return only the response data.
Parameters:
Name Type Attributes Description
pid string PID to download.
options object <optional>
 Request options for ObjectService#fetch.
Overrides:
Source:
Returns:
Response payload.
Type
Promise.<*>

downloadFromWriteTarget(pid, optionsopt) → {Promise.<*>}

Download object content from the repository that accepts writes.
Parameters:
Name Type Attributes Description
pid string PID to download
options object <optional>
 Request options
Source:
Returns:
Response payload
Type
Promise.<*>

fetch(pid, optionsopt) → {Promise.<DataONEHttpResponse>}

Fetch object content and return the full normalized response.
Parameters:
Name Type Attributes Description
pid string PID to fetch.
options object <optional>
 Request options for DataONEService#request.
Source:
Returns:
Full response object.
Type
Promise.<DataONEHttpResponse>

fetchFromLocations(objectServiceUrls, request, token) → {Promise.<DataONEHttpResponse>}

Fetch an object from its registered locations.
Parameters:
Name Type Description
objectServiceUrls Array.<string> Registered object service URLs
request object Built request options
token string Bearer token
Since:
  • 2.39.0
Source:
Returns:
Full response object
Type
Promise.<DataONEHttpResponse>

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

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

getReadClient(baseUrl) → {DataONEHttpClient}

Get a read client for a selected object service URL.
Parameters:
Name Type Description
baseUrl string Object service base URL
Since:
  • 2.39.0
Source:
Returns:
Read client instance
Type
DataONEHttpClient

getReadUrl(pid) → {string}

Build the exact request URL used to read an object.
Parameters:
Name Type Description
pid string PID to read.
Source:
Returns:
Full object request URL.
Type
string

getStore() → {PersistentStorage}

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

getToken() → {Promise.<string>}

Resolve an auth token from MetacatUI when available.
Inherited From:
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.
Inherited From:
Source:
Returns:
Promise resolving to the username, or null if unavailable.
Type
Promise.<(string|null)>

getWriteClient(operation) → {DataONEHttpClient}

Get the write client for create/update requests.
Parameters:
Name Type Description
operation string Operation name for error reporting.
Source:
Throws:
When writeBaseUrl is missing
Type
Error
Returns:
Write client instance.
Type
DataONEHttpClient

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
Inherited From:
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
Inherited From:
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
Inherited From:
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
Inherited From:
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.
Inherited From:
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.
Inherited From:
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
Inherited From:
Source:
Throws:
When the request or identifier parsing fails
Type
Error
Returns:
Response with parsed identifier data.
Type
Promise.<DataONEHttpResponse>

sendTransferRequest(operation, path, method, body, context, optionsopt) → {Promise.<DataONEHttpResponse>}

Execute a create/update transfer request and normalize the XML response.
Parameters:
Name Type Attributes Description
operation string Operation name for error reporting.
path string Request path.
method "POST" | "PUT" HTTP method.
body FormData Multipart payload.
context string Error/parse context.
options object <optional>
 Transfer options.
Source:
Returns:
Parsed identifier response.
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
Inherited From:
Source:
Returns:
Promise resolving to the stored value
Type
Promise.<*>

shouldUseCache() → {Promise.<boolean>}

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

update(params, optionsopt) → {Promise.<DataONEHttpResponse>}

Update an existing DataONE object.
Parameters:
Name Type Attributes Description
params object Update params.
Properties
Name Type Attributes Description
pid string Existing (old) PID.
newPid string Replacement PID.
object * Updated object payload.
sysMetaXml string Updated system metadata XML.
fileName string <optional>
 Optional filename.
options object <optional>
 Transfer options.
Source:
Throws:
When required params are missing or the request fails
Type
Error
Returns:
Update response.
Type
Promise.<DataONEHttpResponse>

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
Inherited From:
Source:
Returns:
Promise resolving to the response.
Type
Promise.<DataONEHttpResponse>

appendObjectBody(formData, objectBody, fileNameopt)

Append object content to multipart form data.
Parameters:
Name Type Attributes Description
formData FormData FormData instance.
objectBody * Object content.
fileName string <optional>
 Optional file name.
Source:

buildTransferFormData(params) → {FormData}

Build the multipart form data for create/update requests.
Parameters:
Name Type Description
params object Transfer params.
Properties
Name Type Attributes Description
pid string Existing or new PID.
newPid string <optional>
 Replacement PID for updates.
object * Object payload.
sysMetaXml string System metadata XML.
fileName string <optional>
 Optional filename.
Source:
Returns:
Multipart form data.
Type
FormData