cocoda-sdk 3.3.3 → 3.4.0

package/dist/esm/errors/index.js

@@ -1,4 +1,12 @@
 class CDKError extends Error {
+  /**
+   * CDKError constructor.
+   *
+   * @param {Object} options
+   * @param {string} [options.message=""] message for the error
+   * @param {Error} [options.relatedError=null] related error
+   * @param {number} [options.code] HTTP status code for the error
+   */
   constructor({ message = "", relatedError = null, code = null } = {}) {
     if (!message && relatedError && relatedError.message) {
       message = relatedError.message;
@@ -10,12 +18,26 @@ class CDKError extends Error {
   }
 }
 class MethodNotImplementedError extends CDKError {
+  /**
+   * MethodNotImplementedError constructor.
+   *
+   * @param {Object} config
+   * @param {string} config.method method that this error refers to
+   * @param {string} [config.message=""] message for the error
+   */
   constructor({ method, message = "", ...options }) {
     options.message = `Method not implemented: ${method} (${message})`;
     super(options);
   }
 }
 class InvalidOrMissingParameterError extends CDKError {
+  /**
+   * InvalidOrMissingParameterError constructor.
+   *
+   * @param {Object} config
+   * @param {string} config.parameter parameter that this error refers to
+   * @param {string} [config.message=""] message for the error
+   */
   constructor({ parameter, message = "", ...options }) {
     options.message = `Invalid or missing parameter: ${parameter} (${message})`;
     super(options);

package/dist/esm/lib/CocodaSDK.js

@@ -23,16 +23,37 @@ providers.addProvider(ConceptApiProvider);
 providers.addProvider(MappingsApiProvider);
 const registryCache = {};
 class CocodaSDK {
+  /**
+   * CDK constructor.
+   *
+   * @param {Object} [config={}] Cocoda-stye config object
+   */
   constructor(config) {
     this.config = config;
     this.axios = axios.create();
   }
+  /**
+   * Method to set the configuration.
+   *
+   * @param {Object} config Cocoda-stye config object
+   */
   setConfig(config) {
     this.config = config;
   }
+  /**
+   * Current configuration.
+   *
+   * @returns {Object} current configuration
+   */
   get config() {
     return this._config;
   }
+  /**
+   * Prepares config when set.
+   *
+   * @param {Object} config Cocoda config object
+   * @private
+   */
   set config(config) {
     config = config || {};
     config.registries = config.registries || [];
@@ -42,16 +63,44 @@ class CocodaSDK {
     });
     this._config = config;
   }
+  /**
+   * Map of registered providers.
+   *
+   * @returns {Object} map of registered providers (name -> provider)
+   */
   get providers() {
     return providers;
   }
+  /**
+   * Creates a new CDK instance (same as `new CocodaSDK(config)`).
+   *
+   * @param {Object} config Cocoda config object
+   * @returns {CocodaSDK} new CDK instance
+   */
   createInstance(config) {
     return new CocodaSDK(config);
   }
+  /**
+   * Offer method to load a config file from URL.
+   *
+   * @param {string} url URL of config as JSON
+   */
   async loadConfig(url) {
     const response = await this.axios.get(url);
     this.config = response.data;
   }
+  /**
+   * Method to load buildInfo.
+   *
+   * Callback will only be called if buildInfo changes; it will not be called when there is no previous value.
+   *
+   * @param {Object} config
+   * @param {string} [config.url] full URL for build-info.json (default is taken from config.cocodaBaseUrl)
+   * @param {Object} [config.buildInfo] current buildInfo
+   * @param {number} [config.interval=60000] interval to load buildInfo in ms
+   * @param {Function} config.callback callback function called with two parameters (error, buildInfo, previousBuildInfo)
+   * @returns {Object} object with two function properties, `stop` to cancel the repeating request, `start` to restart the repeating request, as well as three convenience properties, `isPaused` (whether it is currently paused), `lastResult`, `hasErrored` (whether the last call of the function has errored)
+   */
   loadBuildInfo({ url, buildInfo = null, interval = 6e4, callback, ...config }) {
     if (!url && !this.config.cocodaBaseUrl) {
       throw new errors.CDKError({ message: "Could not determine URL to load build config." });
@@ -78,20 +127,64 @@ class CocodaSDK {
       }
     });
   }
+  /**
+   * Method to get a registry by URI.
+   *
+   * @param {string} uri URI of registry in config
+   * @returns {?Object} initialized registry from config if found
+   */
   getRegistryForUri(uri) {
     return this.config.registries.find((r) => r.uri == uri);
   }
+  /**
+   * Method to initialize registry.
+   *
+   * @param {Object} registry JSKOS registry object
+   * @returns {Object} initialized registry
+   */
   initializeRegistry(registry) {
     registry = providers.init(registry);
     registry.cdk = this;
     return registry;
   }
+  /**
+   * Method to add custom provider.
+   *
+   * @param {Object} provider provider class that extends BaseProvider
+   */
   addProvider(provider) {
     providers.addProvider(provider);
   }
+  /**
+   * Static method to add custom provider.
+   *
+   * @param {Object} provider provider class that extends BaseProvider
+   */
   static addProvider(provider) {
     providers.addProvider(provider);
   }
+  /**
+   * Repeatedly call a certain function.
+   *
+   * Notes:
+   * - Callback will only be called if the results were changed.
+   * - The function will only be repeated after the previous call is resolved. This means that the total interval duration is (interval + duration of function call).
+   *
+   * Example:
+   * ```js
+   *  cdk.repeat({
+   *    function: () => registry.getMappings(),
+   *    callback: (error, result) => console.log(result),
+   *  })
+   * ```
+   *
+   * @param {Object} config
+   * @param {string} config.function a function to be called (can be async)
+   * @param {number} [config.interval=15000] interval in ms
+   * @param {Function} config.callback callback function called with two parameters (error, result, previousResult)
+   * @param {boolean} [config.callImmediately=true] whether to call the function immediately
+   * @returns {Object} object with two function properties, `stop` to cancel the repeating request, `start` to restart the repeating request, as well as three convenience properties, `isPaused` (whether it is currently paused), `lastResult`, `hasErrored` (whether the last call of the function has errored)
+   */
   repeat({ function: func, interval = 15e3, callback, callImmediately = true } = {}) {
     if (!func) {
       throw new errors.InvalidOrMissingParameterError({ parameter: "function" });
@@ -178,6 +271,12 @@ class CocodaSDK {
       }
     };
   }
+  /**
+   * Gets schemes from all registries that support schemes and merges the results.
+   *
+   * @param {Object} [config={}] configuration object that will be used as a parameter for internal `getSchemes` calls
+   * @returns {Object[]} array of JSKOS schemes
+   */
   async getSchemes(config = {}) {
     let schemes = [], promises = [];
     for (let registry of this.config.registries) {
@@ -259,25 +358,29 @@ class CocodaSDK {
         }
         return registry2;
       } else {
-        const provider = Object.values(providers).find((p) => p.providerType === type);
-        if (!provider || !provider._registryConfigForBartocApiConfig) {
-          continue;
-        }
-        const providerName = provider.providerName;
         config.scheme = scheme;
-        config = providers[providerName]._registryConfigForBartocApiConfig(config);
-        if (!config) {
-          continue;
-        }
-        config.provider = providerName;
-        try {
-          registry = this.initializeRegistry(config);
-          if (registry) {
-            registryCache[url] = registry;
-            return registry;
+        for (const provider of Object.values(providers)) {
+          if (provider.providerType && provider.providerType !== type) {
+            continue;
+          }
+          if (!provider._registryConfigForBartocApiConfig) {
+            continue;
+          }
+          const providerName = provider.providerName;
+          const registryConfig = providers[providerName]._registryConfigForBartocApiConfig(config);
+          if (!registryConfig) {
+            continue;
+          }
+          registryConfig.provider = providerName;
+          try {
+            registry = this.initializeRegistry(registryConfig);
+            if (registry) {
+              registryCache[url] = registry;
+              return registry;
+            }
+          } catch (error) {
+            continue;
           }
-        } catch (error) {
-          continue;
         }
       }
     }

package/dist/esm/providers/base-provider.js

@@ -4,9 +4,15 @@ import axios from "axios";
 import * as utils from "../utils/index.js";
 import * as errors from "../errors/index.js";
 class BaseProvider {
+  /**
+   * Provider constructor.
+   *
+   * @param {Object} registry the registry for this provider
+   */
   constructor(registry = {}) {
     this._jskos = registry;
     this.axios = axios.create({
+      // TODO: Decide on timeout value
       timeout: 2e4
     });
     this._path = typeof window !== "undefined" && window.location.pathname;
@@ -20,6 +26,7 @@ class BaseProvider {
     this._repeating = [];
     this._api = {
       status: registry.status,
+      // If `schemes` on registry is an array, remove it because we're only keeping it in this._jskos.schemes
       schemes: Array.isArray(registry.schemes) ? void 0 : registry.schemes,
       top: registry.top,
       data: registry.data,
@@ -165,6 +172,7 @@ class BaseProvider {
       };
     }
   }
+  // Expose some properties from original registry object as getters
   get uri() {
     return this._jskos.uri;
   }
@@ -186,6 +194,11 @@ class BaseProvider {
   get stored() {
     return this._jskos.stored !== void 0 ? this._jskos.stored : this.constructor.stored;
   }
+  /**
+   * Load data about registry via the status endpoint.
+   *
+   * @returns {Promise} Promise that resolves when initialization is complete.
+   */
   async init() {
     if (this._init) {
       return this._init;
@@ -219,17 +232,48 @@ class BaseProvider {
     })();
     return this._init;
   }
+  /**
+   * Preparation to be executed before init. Should be overwritten by subclasses.
+   *
+   * @private
+   */
   _prepare() {
   }
+  /**
+   * Setup to be executed after init. Should be overwritten by subclasses.
+   *
+   * @private
+   */
   _setup() {
   }
+  /**
+   * Returns a source for a axios cancel token.
+   *
+   * @returns {Object} axios cancel token source
+   */
   getCancelTokenSource() {
     return axios.CancelToken.source();
   }
+  /**
+   * Sets authentication credentials.
+   *
+   * @param {Object} options
+   * @param {string} options.key public key of login-server instance the user is authorized for
+   * @param {string} options.bearerToken token that is sent with each request
+   */
   setAuth({ key = this._auth.key, bearerToken = this._auth.bearerToken }) {
     this._auth.key = key;
     this._auth.bearerToken = bearerToken;
   }
+  /**
+   * Sets retry configuration.
+   *
+   * @param {Object} config
+   * @param {string[]} [config.methods=["get", "head", "options"]] HTTP methods to retry (lowercase)
+   * @param {number[]} [config.statusCodes=[401, 403]] status codes to retry
+   * @param {number} [config.count=3] maximum number of retries
+   * @param {number|Function} [config.delay=300*count] a delay in ms or a function that takes the number of current retries and returns a delay in ms
+   */
   setRetryConfig(config = {}) {
     this._retryConfig = Object.assign({
       methods: ["get", "head", "options"],
@@ -240,6 +284,16 @@ class BaseProvider {
       }
     }, config);
   }
+  /**
+   * Returns whether a user is authorized for a certain request.
+   *
+   * @param {Object} options
+   * @param {string} options.type type of item (e.g. mappings)
+   * @param {string} options.action action to be performed (read/create/update/delete)
+   * @param {Object} options.user user object
+   * @param {boolean} [options.crossUser] whether the request is a crossUser request (i.e. updading/deleting another user's item)
+   * @returns {boolean}
+   */
   isAuthorizedFor({ type, action, user, crossUser }) {
     if (action == "read" && this.has[type] === true) {
       return true;
@@ -274,6 +328,12 @@ class BaseProvider {
     }
     return !!this.has[type][action];
   }
+  /**
+   * Returns a boolean whether a certain target scheme is supported or not.
+   *
+   * @param {Object} scheme
+   * @returns {boolean}
+   */
   supportsScheme(scheme) {
     if (!scheme) {
       return false;
@@ -367,6 +427,13 @@ class BaseProvider {
   adjustMappings(mappings) {
     return utils.withCustomProps(mappings.map((mapping) => this.adjustMapping(mapping)), mappings);
   }
+  /**
+   * POSTs multiple mappings. Do not override in subclass!
+   *
+   * @param {Object} config
+   * @param {Array} config.mappings array of mapping objects
+   * @returns {Object[]} array of created mapping objects; in case of failure, consult the `_errors` property on the array at the index of the failed request
+   */
   async postMappings({ mappings, ...config } = {}) {
     if (!mappings || !mappings.length) {
       throw new errors.InvalidOrMissingParameterError({ parameter: "mappings" });
@@ -378,6 +445,13 @@ class BaseProvider {
       config
     });
   }
+  /**
+   * DELETEs multiple mappings. Do not override in subclass!
+   *
+   * @param {Object} config
+   * @param {Array} config.mappings array of mapping objects
+   * @returns {Object[]} array of results (`true` if successful); in case of failure, consult the `_errors` property on the array at the index of the failed request
+   */
   async deleteMappings({ mappings, ...config } = {}) {
     if (!mappings || !mappings.length) {
       throw new errors.InvalidOrMissingParameterError({ parameter: "mappings" });
@@ -389,6 +463,20 @@ class BaseProvider {
       config
     });
   }
+  /**
+   * Calls a method that is for only one item for an array of items. Returns an array of results.
+   *
+   * If there is an error, that index in the result array will be `null`. There is a property `_errors` on the result array that will contain the respective error at the correct index.
+   *
+   * @param {Object} options
+   * @param {string} options.method instance method to call (e.g. `postMapping`)
+   * @param {Object[]} options.items items to call the method for
+   * @param {string} options.itemProperty the property name for the item when calling the method (e.g. `mapping`)
+   * @param {Object} options.config other properties to pass to the method call
+   * @returns {any[]} result array with values returned from individual method calls
+   *
+   * @private
+   */
   async _callHelperForArrayWrappers({ method, items, itemProperty, config }) {
     const errors2 = [];
     const resultItems = await Promise.all(items.map(async (item) => {

package/dist/esm/providers/concept-api-provider.js

@@ -4,6 +4,9 @@ import * as errors from "../errors/index.js";
 import * as utils from "../utils/index.js";
 import jskos from "jskos-tools";
 class ConceptApiProvider extends BaseProvider {
+  /**
+   * @private
+   */
   _prepare() {
     if (this._api.api && this._api.status === void 0) {
       this._api.status = utils.concatUrl(this._api.api, "/status");
@@ -22,6 +25,9 @@ class ConceptApiProvider extends BaseProvider {
       this.has[c] = false;
     });
   }
+  /**
+   * @private
+   */
   _setup() {
     if (this._api.api) {
       const endpoints = {
@@ -55,9 +61,17 @@ class ConceptApiProvider extends BaseProvider {
     this.has.search = !!this._api.search;
     this.has.auth = _.get(this._config, "auth.key") != null;
     this._defaultParams = {
+      // Default parameters mostly for DANTE
       properties: "+created,issued,modified,editorialNote,scopeNote"
     };
   }
+  /**
+   * Used by `registryForScheme` (see src/lib/CocodaSDK.js) to determine a provider config for a concept schceme.
+   *
+   * @param {Object} options
+   * @param {Object} options.url API URL for server
+   * @returns {Object} provider configuration
+   */
   static _registryConfigForBartocApiConfig({ url, scheme } = {}) {
     if (!url || !scheme) {
       return null;
@@ -67,6 +81,11 @@ class ConceptApiProvider extends BaseProvider {
       schemes: [scheme]
     };
   }
+  /**
+   * Returns the main vocabulary URI by requesting the scheme info and saving it in a cache.
+   *
+   * @private
+   */
   async _getSchemeUri(scheme) {
     this._approvedSchemes = this._approvedSchemes || [];
     this._rejectedSchemes = this._rejectedSchemes || [];
@@ -95,6 +114,12 @@ class ConceptApiProvider extends BaseProvider {
       return null;
     }
   }
+  /**
+   * Returns all concept schemes.
+   *
+   * @param {Object} config
+   * @returns {Object[]} array of JSKOS concept scheme objects
+   */
   async getSchemes(config) {
     if (!this._api.schemes) {
       if (Array.isArray(this.schemes)) {
@@ -108,6 +133,7 @@ class ConceptApiProvider extends BaseProvider {
       url: this._api.schemes,
       params: {
         ...this._defaultParams,
+        // ? What should the default limit be?
         limit: 500,
         ...config.params || {}
       }
@@ -118,6 +144,13 @@ class ConceptApiProvider extends BaseProvider {
       return schemes;
     }
   }
+  /**
+   * Returns top concepts for a concept scheme.
+   *
+   * @param {Object} config
+   * @param {Object} config.scheme concept scheme object
+   * @returns {Object[]} array of JSKOS concept objects
+   */
   async getTop({ scheme, ...config }) {
     if (!this._api.top) {
       throw new errors.MissingApiUrlError();
@@ -138,12 +171,20 @@ class ConceptApiProvider extends BaseProvider {
       url: this._api.top,
       params: {
         ...this._defaultParams,
+        // ? What should the default limit be?
         limit: 1e4,
         ...config.params || {},
         uri: schemeUri
       }
     });
   }
+  /**
+   * Returns details for a list of concepts.
+   *
+   * @param {Object} config
+   * @param {Object[]} config.concepts list of concept objects to load
+   * @returns {Object[]} array of JSKOS concept objects
+   */
   async getConcepts({ concepts, ...config }) {
     if (this.has.data === false) {
       throw new errors.MissingApiUrlError();
@@ -161,12 +202,20 @@ class ConceptApiProvider extends BaseProvider {
       url: this._api.data,
       params: {
         ...this._defaultParams,
+        // ? What should the default limit be?
         limit: 500,
         ...config.params || {},
         uri: uris.join("|")
       }
     });
   }
+  /**
+   * Returns narrower concepts for a concept.
+   *
+   * @param {Object} config
+   * @param {Object} config.concept concept object
+   * @returns {Object[]} array of JSKOS concept objects
+   */
   async getNarrower({ concept, ...config }) {
     if (!this._api.narrower) {
       throw new errors.MissingApiUrlError();
@@ -180,12 +229,20 @@ class ConceptApiProvider extends BaseProvider {
       url: this._api.narrower,
       params: {
         ...this._defaultParams,
+        // ? What should the default limit be?
         limit: 1e4,
         ...config.params || {},
         uri: concept.uri
       }
     });
   }
+  /**
+   * Returns ancestor concepts for a concept.
+   *
+   * @param {Object} config
+   * @param {Object} config.concept concept object
+   * @returns {Object[]} array of JSKOS concept objects
+   */
   async getAncestors({ concept, ...config }) {
     if (!this._api.ancestors) {
       throw new errors.MissingApiUrlError();
@@ -199,12 +256,25 @@ class ConceptApiProvider extends BaseProvider {
       url: this._api.ancestors,
       params: {
         ...this._defaultParams,
+        // ? What should the default limit be?
         limit: 1e4,
         ...config.params || {},
         uri: concept.uri
       }
     });
   }
+  /**
+   * Returns suggestion result in OpenSearch Suggest Format.
+   *
+   * @param {Object} config
+   * @param {string} config.search search string
+   * @param {Object} [config.scheme] concept scheme to search in
+   * @param {number} [config.limit=100] maximum number of search results (default might be overridden by registry)
+   * @param {string} [config.use=notation,label] which fields to search ("notation", "label" or "notation,label")
+   * @param {string[]} [config.types=[]] list of type URIs
+   * @param {string} [config.sort=score] sorting parameter
+   * @returns {Array} result in OpenSearch Suggest Format
+   */
   async suggest({ use = "notation,label", types = [], sort = "score", params = {}, ...config }) {
     return this._search({
       ...config,
@@ -217,6 +287,17 @@ class ConceptApiProvider extends BaseProvider {
       }
     });
   }
+  /**
+   * Returns search results in JSKOS Format.
+   *
+   * @param {Object} config
+   * @param {string} config.search search string
+   * @param {Object} [config.scheme] concept scheme to search in
+   * @param {number} [config.limit=100] maximum number of search results (default might be overridden by registry)
+   * @param {number} [config.offset=0] offset
+   * @param {string[]} [config.types=[]] list of type URIs
+   * @returns {Array} result in JSKOS Format
+   */
   async search({ types = [], params = {}, ...config }) {
     return this._search({
       ...config,
@@ -227,6 +308,16 @@ class ConceptApiProvider extends BaseProvider {
       }
     });
   }
+  /**
+   * Returns concept scheme suggestion result in OpenSearch Suggest Format.
+   *
+   * @param {Object} config
+   * @param {string} config.search search string
+   * @param {number} [config.limit=100] maximum number of search results (default might be overridden by registry)
+   * @param {string} [config.use=notation,label] which fields to search ("notation", "label" or "notation,label")
+   * @param {string} [config.sort=score] sorting parameter
+   * @returns {Array} result in OpenSearch Suggest Format
+   */
   async vocSuggest({ use = "notation,label", sort = "score", params = {}, ...config }) {
     return this._search({
       ...config,
@@ -238,6 +329,15 @@ class ConceptApiProvider extends BaseProvider {
       }
     });
   }
+  /**
+   * Returns concept scheme search results in JSKOS Format.
+   *
+   * @param {Object} config
+   * @param {string} config.search search string
+   * @param {number} [config.limit=100] maximum number of search results (default might be overridden by registry)
+   * @param {number} [config.offset=0] offset
+   * @returns {Array} result in JSKOS Format
+   */
   async vocSearch(config) {
     return this._search({
       ...config,
@@ -263,6 +363,7 @@ class ConceptApiProvider extends BaseProvider {
         ...params,
         limit,
         count: limit,
+        // Some endpoints use count instead of limit
         offset,
         search,
         query: search,
@@ -272,6 +373,13 @@ class ConceptApiProvider extends BaseProvider {
       url
     });
   }
+  /**
+   * Returns a list of types.
+   *
+   * @param {Object} config
+   * @param {Object} [config.scheme] concept scheme to load types for
+   * @returns {Object[]} array of JSKOS type objects
+   */
   async getTypes({ scheme, ...config }) {
     if (!this._api.types) {
       throw new errors.MissingApiUrlError();

package/dist/esm/providers/index.js

@@ -8,11 +8,13 @@ import LabelSearchSuggestionProvider from "./label-search-suggestion-provider.js
 import SkosmosApiProvider from "./skosmos-api-provider.js";
 import LocApiProvider from "./loc-api-provider.js";
 import SkohubProvider from "./skohub-provider.js";
+import LobidApiProvider from "./lobid-api-provider.js";
 import MyCoReProvider from "./mycore-provider.js";
 export {
   BaseProvider,
   ConceptApiProvider,
   LabelSearchSuggestionProvider,
+  LobidApiProvider,
   LocApiProvider,
   LocalMappingsProvider,
   MappingsApiProvider,