cocoda-sdk 1.0.13 → 2.0.0

package/providers/concept-api-provider.js

@@ -1,377 +0,0 @@
-const BaseProvider = require("./base-provider")
-const _ = require("../utils/lodash")
-const errors = require("../errors")
-const utils = require("../utils")
-const jskos = require("jskos-tools")
-
-/**
- * JSKOS Concept API.
- *
- * This class provides access to concept schemes and their concepts via JSKOS API in [JSKOS format](https://gbv.github.io/jskos/).
- * See [jskos-server](https://github.com/gbv/jskos-server) for a JSKOS API reference implementation and [DANTE](https://api.dante.gbv.de/) for another API endpoint.
- *
- * To use it in a registry, specify `provider` as "ConceptApi" and provide the API base URL as `api`:
- * ```json
- * {
- *  "uri": "http://coli-conc.gbv.de/registry/coli-conc-concepts",
- *  "provider": "ConceptApi",
- *  "api": "https://coli-conc.gbv.de/api/"
- * }
- * ```
- *
- * If the `/status` endpoint can be queried, the remaining API methods will be taken from that. As a fallback, the default endpoints will be appended to `api`.
- *
- * Alternatively, you can provide the endpoints separately: `status`, `schemes`, `top`, `concepts`, `data`, `narrower`, `ancestors`, `types`, `suggest`, `search`
- * Note that `schemes`, `top`, and `types` can also be provided as arrays.
- *
- * Additionally, the following JSKOS properties can be provided: `prefLabel`, `notation`, `definition`
- *
- * @extends BaseProvider
- * @category Providers
- */
-class ConceptApiProvider extends BaseProvider {
-
-  /**
-   * @private
-   */
-  _prepare() {
-    // Set status endpoint only
-    if (this._api.api && this._api.status === undefined) {
-      this._api.status = utils.concatUrl(this._api.api, "/status")
-    }
-  }
-
-  /**
-   * @private
-   */
-  _setup() {
-    // Implicitly fill `this._api` if necessary
-    if (this._api.api) {
-      const endpoints = {
-        schemes: "/voc",
-        top: "/voc/top",
-        concepts: "/voc/concepts",
-        data: "/data",
-        narrower: "/narrower",
-        ancestors: "/ancestors",
-        types: "/types",
-        suggest: "/suggest",
-        search: "/search",
-      }
-      for (let key of Object.keys(endpoints)) {
-        // Only override if undefined
-        if (this._api[key] === undefined) {
-          this._api[key] = utils.concatUrl(this._api.api, endpoints[key])
-        }
-      }
-    }
-    this.has.schemes = !!this._api.schemes
-    this.has.top = !!this._api.top
-    this.has.data = !!this._api.data
-    this.has.concepts = !!this._api.concepts || this.has.data
-    this.has.narrower = !!this._api.narrower
-    this.has.ancestors = !!this._api.ancestors
-    this.has.types = !!this._api.types
-    this.has.suggest = !!this._api.suggest
-    this.has.search = !!this._api.search
-    this.has.auth = _.get(this._config, "auth.key") != null
-    this._defaultParams = {
-      properties: "uri,prefLabel,notation,inScheme",
-    }
-  }
-
-  /**
-   * Returns all concept schemes.
-   *
-   * @param {Object} config
-   * @returns {Object[]} array of JSKOS concept scheme objects
-   */
-  async getSchemes(config) {
-    if (!this._api.schemes) {
-      throw new errors.MissingApiUrlError()
-    }
-    if (Array.isArray(this._api.schemes)) {
-      return this._api.schemes
-    }
-    const schemes = await this.axios({
-      ...config,
-      method: "get",
-      url: this._api.schemes,
-      params: {
-        ...this._defaultParams,
-        // ? What should the default limit be?
-        limit: 500,
-        ...(config.params || {}),
-      },
-    })
-    // If schemes were given in registry object, only request those schemes from API
-    if (Array.isArray(this._jskos.schemes)) {
-      return utils.withCustomProps(schemes.filter(s => jskos.isContainedIn(s, this._jskos.schemes)), schemes)
-    } else {
-      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()
-    }
-    if (!scheme) {
-      throw new errors.InvalidOrMissingParameterError({ parameter: "scheme" })
-    }
-    if (Array.isArray(this._api.top)) {
-      return this._api.top
-    }
-    return this.axios({
-      ...config,
-      method: "get",
-      url: this._api.top,
-      params: {
-        ...this._defaultParams,
-        // ? What should the default limit be?
-        limit: 10000,
-        ...(config.params || {}),
-        uri: scheme.uri,
-      },
-    })
-  }
-
-  /**
-   * 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) {
-      throw new errors.MissingApiUrlError()
-    }
-    if (!concepts) {
-      throw new errors.InvalidOrMissingParameterError({ parameter: "concepts" })
-    }
-    if (!Array.isArray(concepts)) {
-      concepts = [concepts]
-    }
-    let uris = concepts.map(concept => concept.uri).filter(uri => uri != null)
-    return this.axios({
-      ...config,
-      method: "get",
-      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()
-    }
-    if (!concept || !concept.uri) {
-      throw new errors.InvalidOrMissingParameterError({ parameter: "concept" })
-    }
-    return this.axios({
-      ...config,
-      method: "get",
-      url: this._api.narrower,
-      params: {
-        ...this._defaultParams,
-        // ? What should the default limit be?
-        limit: 10000,
-        ...(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()
-    }
-    if (!concept || !concept.uri) {
-      throw new errors.InvalidOrMissingParameterError({ parameter: "concept" })
-    }
-    return this.axios({
-      ...config,
-      method: "get",
-      url: this._api.ancestors,
-      params: {
-        ...this._defaultParams,
-        // ? What should the default limit be?
-        limit: 10000,
-        ...(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({ scheme, use = "notation,label", types = [], sort = "score", ...config }) {
-    return this._search({
-      ...config,
-      endpoint: "suggest",
-      params: {
-        ...config.params,
-        voc: _.get(scheme, "uri", ""),
-        type: types.join("|"),
-        use,
-        sort,
-      },
-    })
-  }
-
-  /**
-   * 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({ scheme, types = [], ...config }) {
-    return this._search({
-      ...config,
-      endpoint: "search",
-      params: {
-        ...config.params,
-        voc: _.get(scheme, "uri", ""),
-        type: types.join("|"),
-      },
-    })
-  }
-
-  /**
-   * 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", ...config }) {
-    return this._search({
-      ...config,
-      endpoint: "voc-suggest",
-      params: {
-        ...config.params,
-        use,
-        sort,
-      },
-    })
-  }
-
-  /**
-   * 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,
-      endpoint: "voc-search",
-    })
-  }
-
-  async _search({ endpoint, search, limit, offset, params, ...config }) {
-    let url = this._api[endpoint]
-    if (!url) {
-      throw new errors.MissingApiUrlError()
-    }
-    if (!search) {
-      throw new errors.InvalidOrMissingParameterError({ parameter: "search" })
-    }
-    limit = limit || this._jskos.suggestResultLimit || 100
-    offset = offset || 0
-    // Some registries use URL templates with {searchTerms}
-    url = url.replace("{searchTerms}", search)
-    return this.axios({
-      ...config,
-      params: {
-        ...this._defaultParams,
-        ...params,
-        limit: limit,
-        count: limit, // Some endpoints use count instead of limit
-        offset,
-        search,
-        query: search,
-      },
-      method: "get",
-      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()
-    }
-    if (Array.isArray(this._api.types)) {
-      return this._api.types
-    }
-    if (scheme && scheme.uri) {
-      _.set(config, "params.uri", scheme.uri)
-    }
-    return this.axios({
-      ...config,
-      method: "get",
-      url: this._api.types,
-    })
-  }
-
-}
-
-ConceptApiProvider.providerName = "ConceptApi"
-
-module.exports = ConceptApiProvider

package/providers/index.js

@@ -1,34 +0,0 @@
-const errors = require("../errors")
-const BaseProvider = require("./base-provider")
-
-let providers = {
-  [BaseProvider.providerName]: BaseProvider,
-  init(registry) {
-    if (this[registry.provider]) {
-      return new this[registry.provider](registry)
-    }
-    throw new errors.InvalidProviderError()
-  },
-  addProvider(provider) {
-    if (provider.prototype instanceof providers[BaseProvider.providerName]) {
-      this[provider.providerName] = provider
-    } else {
-      throw new errors.InvalidProviderError()
-    }
-  },
-}
-
-for (let provider of [
-  require("./local-mappings-provider"),
-  require("./mappings-api-provider"),
-  require("./occurrences-api-provider"),
-  require("./concept-api-provider"),
-  require("./reconciliation-api-provider"),
-  require("./label-search-suggestion-provider"),
-  require("./skosmos-api-provider"),
-  require("./loc-api-provider"),
-]) {
-  providers.addProvider(provider)
-}
-
-module.exports = providers

package/providers/label-search-suggestion-provider.js

@@ -1,219 +0,0 @@
-const BaseProvider = require("./base-provider")
-const jskos = require("jskos-tools")
-const _ = require("../utils/lodash")
-const errors = require("../errors")
-
-// TODO: Only keep the last 20 results in cache.
-// TODO: Try to remove dependencies on `selected`, `scheme._registry.registry.uri`, etc.
-
-/**
- * Label search suggestion provider.
- *
- * This provider offers mapping recommendations based on label match via the `/search` endpoint of JSKOS APIs.
- *
- * The provider requires that a list of initialized registries with search endpoints is provided via `setRegistries`. Note that it has further dependencies on Cocoda and might be adjusted to reduce these dependencies.
- *
- * To use it in a registry, specify `provider` as "LabelSearchSuggestion":
- * ```json
- * {
- *  "uri": "http://coli-conc.gbv.de/registry/coli-conc-recommendations"
- *  "provider": "LabelSearchSuggestion"
- * }
- * ```
- *
- * You can provide a list of excluded schemes as JSKOS objects in `excludedSchemes`.
- *
- * Additionally, the following JSKOS properties can be provided: `prefLabel`, `notation`, `definition`
- *
- * @extends BaseProvider
- * @category Providers
- */
-class LabelSearchSuggestionProvider extends BaseProvider {
-
-  /**
-   * @private
-   */
-  _setup() {
-    this._cache = []
-    this.has.mappings = true
-  }
-
-  /**
-   * Sets a local list of registries where the search providers are taken from.
-   *
-   * @param {Object[]} registries list of registries
-   */
-  setRegistries(registries) {
-    this._registries = registries
-  }
-
-  /**
-   * List of search provider URIs.
-   *
-   * @private
-   */
-  get _searchUris() {
-    const _searchUris = {}
-    for (let registry of this._registries) {
-      const search = _.get(registry, "_api.search") || _.get(registry, "_jskos.search") || registry.search
-      if (search && _.isString(search)) {
-        _searchUris[registry.uri] = search
-      }
-    }
-    return _searchUris
-  }
-
-  /**
-   * Override `supportsScheme` to check whether a search URI is available for the scheme's registry.
-   *
-   * @param {Object} scheme - target scheme to check for support
-   * @returns {boolean}
-   */
-  supportsScheme(scheme) {
-    let targetRegistry = _.get(scheme, "_registry.uri")
-    return super.supportsScheme(scheme) && targetRegistry != null && this._searchUris && this._searchUris[targetRegistry]
-  }
-
-  /**
-   * Returns a list of mappings.
-   *
-   * @param {Object} config
-   * @param {Object} config.from JSKOS concept on from side
-   * @param {Object} config.to JSKOS concept on to side
-   * @param {Object} config.mode mappings mode
-   * @param {Object} config.selected selected mappings in Cocoda
-   * @returns {Object[]} array of JSKOS mapping objects
-   */
-  async getMappings({ from, to, mode, selected, limit = 10, ...config }) {
-    // TODO: Why mode?
-    if (mode != "or") {
-      return []
-    }
-    if (!this._searchUris) {
-      throw new errors.MissingApiUrlError({ message: "No registries available to search" })
-    }
-    if (!selected) {
-      throw new errors.InvalidOrMissingParameterError({ parameter: "selected" })
-    }
-    let promises = []
-    if (from && this.supportsScheme(selected.scheme[false])) {
-      promises.push(this._getMappings({ ...config, concept: from, sourceScheme: selected.scheme[true], targetScheme: selected.scheme[false], limit }))
-    } else {
-      promises.push(Promise.resolve([]))
-    }
-    if (to && this.supportsScheme(selected.scheme[true])) {
-      promises.push(this._getMappings({ ...config, concept: to, sourceScheme: selected.scheme[false], targetScheme: selected.scheme[true], limit, swap: true }))
-    } else {
-      promises.push(Promise.resolve([]))
-    }
-    let [fromResult, toResult] = await Promise.all(promises)
-    // Filter all duplicates from toResult
-    toResult = toResult.filter(m => !fromResult.find(n => jskos.compareMappingMembers(m, n)))
-    // Reduce number of results until limit is reached
-    while (fromResult.length + toResult.length > limit) {
-      if (toResult.length >= fromResult.length) {
-        toResult = toResult.slice(0, -1)
-      } else {
-        fromResult = fromResult.slice(0, -1)
-      }
-    }
-    return _.union(fromResult, toResult)
-  }
-
-  /**
-   * Internal function to get mapping recommendations for a certain concept with sourceScheme and targetScheme.
-   *
-   * @private
-   *
-   * @param {Object} config
-   * @param {Object} config.concept
-   * @param {Object} config.sourceScheme
-   * @param {Pbject} config.targetScheme
-   * @param {boolean} config.swap - whether to reverse the direction of the mappings
-   */
-  async _getMappings({ concept, sourceScheme, targetScheme, limit, swap = false, ...config }) {
-    if (!concept || !sourceScheme || !targetScheme) {
-      return []
-    }
-    // If source scheme is the same as target scheme, skip
-    if (jskos.compare(sourceScheme, targetScheme)) {
-      return []
-    }
-    // Prepare label
-    // TODO: Can we use a language prioritiy list like for requests?
-    let label = jskos.prefLabel(concept, {
-      fallbackToUri: false,
-      language: this.languages[0] || this._defaultLanguages[0],
-    })
-    if (!label) {
-      return []
-    }
-    // Get results from API or cache
-    const results = await this._getResults({ ...config, label, targetScheme, limit })
-    // Map results to actual mappings
-    let mappings = results.map(result => ({
-      fromScheme: sourceScheme,
-      from: { memberSet: [concept] },
-      toScheme: targetScheme,
-      to: { memberSet: [result] },
-      type: ["http://www.w3.org/2004/02/skos/core#mappingRelation"],
-    }))
-    if (swap) {
-      // Swap mapping sides if only `to` was set
-      mappings = mappings.map(mapping => Object.assign(mapping, {
-        fromScheme: mapping.toScheme,
-        from: mapping.to,
-        toScheme: mapping.fromScheme,
-        to: mapping.from,
-      }))
-    }
-    return mappings
-  }
-
-  /**
-   * Internal function that either makes an API request or uses a local cache.
-   *
-   * @private
-   *
-   * @param {Object} config
-   * @param {string} config.label
-   * @param {Object} config.targetScheme
-   */
-  async _getResults({ label, targetScheme, limit, ...config }) {
-    // Use local cache.
-    let resultsFromCache = (this._cache[targetScheme.uri] || {})[label]
-    if (resultsFromCache && resultsFromCache._limit >= limit) {
-      return resultsFromCache
-    }
-    // Determine search URI for target scheme's registry
-    const targetRegistry = _.get(targetScheme, "_registry.uri")
-    const url = targetRegistry != null && this._searchUris && this._searchUris[targetRegistry]
-    if (!url) {
-      return []
-    }
-    // API request
-    const data = await this.axios({
-      ...config,
-      method: "get",
-      url,
-      params: {
-        query: label,
-        limit,
-        voc: targetScheme.uri,
-      },
-    })
-    // Save result in cache
-    if (!this._cache[targetScheme.uri]) {
-      this._cache[targetScheme.uri] = {}
-    }
-    this._cache[targetScheme.uri][label] = data
-    this._cache[targetScheme.uri][label]._limit = limit
-    return data
-  }
-
-}
-
-LabelSearchSuggestionProvider.providerName = "LabelSearchSuggestion"
-LabelSearchSuggestionProvider.stored = false
-
-module.exports = LabelSearchSuggestionProvider