jskos-server 2.4.0

package/services/registries.js

@@ -0,0 +1,319 @@
+import _ from "lodash"
+import { removeNullProperties } from "../utils/utils.js"
+import { validate } from "jskos-validate"
+import { Registry } from "../models/registries.js"
+import { addKeywords } from "../utils/searchHelper.js"
+import { EntityNotFoundError, DatabaseAccessError, InvalidBodyError, MalformedBodyError } from "../errors/index.js"
+
+import { AbstractService } from "./abstract.js"
+
+// TODO: get via factory Method
+import { models } from "../models/index.js"
+
+export class RegistryService extends AbstractService {
+  static allMemberTypes = ["schemes", "concepts", "mappings", "concordances", "annotations", "registries"]
+
+  constructor(config) {
+    super(config)
+    this.config = config.registries || {}
+    this.types = {}
+
+    this.model = Registry
+
+    // TODO: duplicated code in config.setup
+    for (let type of RegistryService.allMemberTypes) {
+      this.types[type] = config.types?.[type]
+      if (this.types[type] === true) {
+        this.types[type] = { mustExist: false, skipInvalid: false }
+      }
+      if (this.types[type] && !("uriRequired" in this.types[type])) {
+        this.types[type].uriRequired = true
+      }
+    }
+  }
+
+  /**
+   * Retrieves registry entries.
+   *
+   * @param {Object} query - Query parameters controlling pagination.
+   * @param {number|string} [query.limit=100] - Maximum number of registries to fetch.
+   * @param {number|string} [query.offset=0] - Number of registries to skip before fetching.
+   * @returns {Promise<Object[]>} A promise that resolves to the matching registries.
+   */
+  async queryItems(query) {
+    const { limit, offset } = this._getLimitAndOffset(query)
+    return this.model.find({}).skip(offset).limit(limit).lean().exec()
+  }
+
+  /**
+   * Prepares and checks a registry before inserting/updating:
+   * - validates object, throws error if it doesn't (create/update)
+   * - add `_id` property (create/update)
+   * - add search keyword fields for text index (create/update)
+   *
+   * @param {Object} registry registry object
+   * @param {string} action one of "create" or "update"
+   * @returns {Object} prepared registry
+   */
+  async prepareAndCheckItemForAction(registry, action) {
+    if (typeof registry !== "object") {
+      throw new MalformedBodyError("Invalid registry object")
+    }
+
+    if (["create", "update"].includes(action)) {
+      // Validate registry
+      if (!validate.registry(registry)) {
+        // TODO: use error object
+        const msgs = validate.registry.errorMessages || ["Registry validation failed"]
+        throw new InvalidBodyError(msgs.join("; "))
+      }
+      if (!registry.uri) {
+        // TODO: how about minting URIs?
+        throw new InvalidBodyError("Registry lacks uri")
+      }
+
+      await this.processMembers(registry)
+
+      // Add _id
+      registry._id = registry.uri
+
+      // Add index keywords
+      addKeywords(registry)
+
+      // Remove created for update action // TODO: why?
+      if (action === "update") {
+        delete registry.created
+      }
+    }
+    return registry
+  }
+
+
+  /**
+   * Updates an existing registry entry, while preserving immutable fields.
+   *
+   * @param {Object} params - Parameters for updating the registry.
+   * @param {Object} params.body - The new registry data to store.
+   * @param {Object} params.existing - The existing registry document from the database.
+   * @returns {Promise<Object>} The updated registry document.
+   * @throws {InvalidBodyError} If the request body is missing or fails validation.
+   * @throws {EntityNotFoundError} If the targeted registry is not found.
+   * @throws {DatabaseAccessError} If the database operation fails.
+   */
+  async updateItem({ body, existing }) {
+    if (!body) {
+      throw new InvalidBodyError()
+    }
+
+    body.modified = new Date().toISOString()
+
+    delete body.type
+
+    // Validate registry
+    if (!validate.registry(body)) {
+      const msgs = validate.registry?.errorMessages || []
+      throw new InvalidBodyError(
+        msgs.join("; ") || "Registry validation failed",
+      )
+    }
+
+    await this.processMembers(body)
+
+    // Preserve existing property: created date
+    body.created = existing.created
+
+    // Override _id and id properties
+    body.id = existing.id
+    body._id = existing._id
+
+    // Replace in database
+    const result = await this.model.replaceOne({ _id: existing._id }, body)
+    if (!result.matchedCount) {
+      throw new EntityNotFoundError(`Registry not found: ${existing._id}`)
+    }
+
+    // Confirm that the update was acknowledged
+    if (!result.acknowledged) {
+      throw new DatabaseAccessError()
+    }
+
+    // Return the updated registry entry
+    const doc = await this.model.findById(existing._id).lean()
+    if (!doc) {
+      throw new DatabaseAccessError()
+    }
+
+    return doc
+  }
+
+  /**
+   * Partially updates a registry entry.
+   *
+   * @async
+   * @function patchRegistry
+   * @param {Object} params - Parameters for updating a registry.
+   * @param {Object} params.body - Incoming registry fields to merge into the existing entry.
+   * @param {Object} params.existing - The existing registry document from the database to be updated.
+   * @throws {InvalidBodyError} If the request body is missing or fails validation.
+   * @throws {EntityNotFoundError} If the target registry does not exist.
+   * @throws {DatabaseAccessError} If the database update fails.
+   * @returns {Promise<Object>} The updated registry document from the database.
+   */
+  async patchRegistry({ body, existing }) {
+    if (!body) {
+      throw new InvalidBodyError()
+    }
+    if (!existing?._id) {
+      throw new EntityNotFoundError("Registry not found")
+    }
+
+    existing.modified = new Date().toISOString()
+
+    // Protect identity + server-managed fields
+    for (let key of ["_id", "id", "uri", "created"]) {
+      delete body[key]
+    }
+
+    // Merge existing with updates
+    _.assign(existing, body)
+
+    removeNullProperties(existing)
+
+    await this.processMembers(existing)
+
+    // Validate merged object
+    if (!validate.registry(existing)) {
+      const msgs = validate.registry.errorMessages || []
+      throw new InvalidBodyError(
+        msgs.join("; ") || "Registry validation failed",
+      )
+    }
+
+    // Replace in database
+    const result = await this.model.replaceOne({ _id: existing._id }, existing)
+    if (!result.matchedCount) {
+      throw new EntityNotFoundError(`Registry not found: ${existing._id}`)
+    }
+
+    // Confirm that the update was acknowledged
+    if (!result.acknowledged) {
+      throw new DatabaseAccessError()
+    }
+
+    // Return the updated registry entry
+    const doc = await this.model.findById(existing._id).lean()
+    if (!doc) {
+      throw new DatabaseAccessError()
+    }
+
+    return doc
+  }
+
+  /**
+   * Initializes the Registry collection by creating it if absent, removing any existing indexes,
+   * and establishing the full set of required indexes
+   */
+  async createIndexes() {
+    const indexes = []
+    indexes.push([{ uri: 1 }, {}])
+    indexes.push([{ identifier: 1 }, {}])
+    indexes.push([{ notation: 1 }, {}])
+    indexes.push([{ type: 1 }, {}])
+
+    indexes.push([{ created: 1 }, {}])
+    indexes.push([{ modified: 1 }, {}])
+    indexes.push([{ startDate: 1 }, {}])
+    indexes.push([{ endDate: 1 }, {}])
+
+    indexes.push([{ url: 1 }, {}])
+    indexes.push([{ "subject.uri": 1 }, {}])
+
+    // TODO: check this
+    indexes.push([{ _keywordsLabels: 1 }, {}])
+    indexes.push([{ _keywordsPublisher: 1 }, {}])
+    indexes.push([{ "_keywordsLabels.0": 1 }, {}])
+    indexes.push([
+      {
+        _keywordsNotation: "text",
+        _keywordsLabels: "text",
+        _keywordsOther: "text",
+        _keywordsPublisher: "text",
+      },
+      {
+        name: "text",
+        default_language: "german", // ??
+        weights: {
+          _keywordsNotation: 10,
+          _keywordsLabels: 6,
+          _keywordsOther: 3,
+          _keywordsPublisher: 3,
+        },
+      },
+    ])
+
+    // Create collection if necessary
+    try {
+      await this.model.createCollection()
+    } catch (error) {
+      this.error("Error creating collection:", error)
+      // Ignore error
+    }
+
+    // Drop existing indexes
+    await this.model.collection.dropIndexes()
+    for (const [index, options] of indexes) {
+      await this.model.collection.createIndex(index, options)
+    }
+  }
+
+  /**
+   * Validates and filters registry member fields based on config.
+   *
+   * @param {Object} registry registry object
+   * @throws {InvalidBodyError} When a disallowed membership field is present.
+   */
+  async processMembers(registry) {
+    const usedTypes = RegistryService.allMemberTypes.filter(type => registry[type])
+
+    if (!this.config.mixedTypes) {
+      if (usedTypes.length > 1) {
+        throw new InvalidBodyError(`Registry must not have multiple member types, found: ${usedTypes.join(", ")}`)
+      }
+    }
+
+    for (let type of usedTypes) {
+      if (!this.config.types[type]) {
+        throw new InvalidBodyError(`Registry member type not allowed: ${type}`)
+      }
+
+      const { uriRequired, mustExist, skipInvalid } = this.config.types[type]
+
+      const validator = validate[type.replace(/ies$/,"y").replace(/s$/,"")]
+
+      let items = []
+      for (let item of registry[type].filter(item => item !== null)) {
+        let error
+        if (uriRequired && !item.uri) {
+          error = `missing ${type} uri in registry`
+        } else if (!validator(item)) {
+          error = `invalid ${type} in registry`
+          // TODO: use validator.errors error object
+        } else if (mustExist) {
+          const found = await models[type].findOne({ uri: item.uri }).lean()
+          if (!found) {
+            error = `${type} not found with uri: ${item.uri}`
+          }
+        }
+        if (error) {
+          if (!skipInvalid) {
+            throw new InvalidBodyError(error)
+          }
+        } else {
+          items.push(item)
+        }
+      }
+      registry[type] = items
+    }
+
+  }
+}

package/services/schemes.js

@@ -0,0 +1,318 @@
+import _ from "lodash"
+import { validate } from "jskos-validate"
+
+import { addKeywords } from "../utils/searchHelper.js"
+import { MalformedBodyError, MalformedRequestError, EntityNotFoundError, DatabaseAccessError, InvalidBodyError } from "../errors/index.js"
+import { Scheme } from "../models/schemes.js"
+import { Concept } from "../models/concepts.js"
+
+import { AbstractService } from "./abstract.js"
+
+export class SchemeService extends AbstractService {
+
+  constructor(config) {
+    super(config)
+    this.baseUrl = config.baseUrl
+    this.model = Scheme
+  }
+
+  /**
+   * Return a Promise with an array of vocabularies.
+   */
+  async queryItems(query) {
+    let mongoQuery = {}
+    if (query.uri) {
+      mongoQuery = {
+        $or: query.uri.split("|").map(uri => ({ uri })).concat(query.uri.split("|").map(uri => ({ identifier: uri }))),
+      }
+    }
+    if (query.type) {
+      mongoQuery.type = query.type
+    }
+    if (query.languages) {
+      mongoQuery.languages = {
+        $in: query.languages.split(","),
+      }
+    }
+    if (query.subject) {
+      mongoQuery["subject.uri"] = {
+        $in: query.subject.split("|"),
+      }
+    }
+    if (query.license) {
+      mongoQuery["license.uri"] = {
+        $in: query.license.split("|"),
+      }
+    }
+    if (query.partOf) {
+      mongoQuery["partOf.uri"] = {
+        $in: query.partOf.split("|"),
+      }
+    }
+    if (query.publisher) {
+      mongoQuery._keywordsPublisher = query.publisher
+    }
+    if (query.notation) {
+      const notations = query.notation.split("|")
+      mongoQuery.notation = { $in: notations }
+    }
+
+    // Sort order (default: asc = 1)
+    const order = query.order === "desc" ? -1 : 1
+    const sort = {}
+    switch (query.sort) {
+      case "label":
+        sort["_keywordsLabels.0"] = order
+        break
+      case "notation":
+        sort["_keywordsNotation.0"] = order
+        break
+      case "created":
+        sort["created"] = order
+        break
+      case "modified":
+        sort["modified"] = order
+        break
+      case "counter":
+        sort["_uriSuffixNumber"] = order
+        break
+    }
+
+    // Build aggregation pipeline
+    const pipeline = [
+      { $match: mongoQuery },
+    ]
+    if (query.sort === "counter") {
+      // Add an additional aggregation step to add _uriSuffixNumber property
+      pipeline.push({
+        $set: {
+          _uriSuffixNumber: {
+            $function: {
+              body: function (uri) {
+                return parseInt(uri.substring(uri.lastIndexOf("/") + 1))
+              },
+              args: ["$uri"],
+              lang: "js",
+            },
+          },
+        },
+      })
+    }
+    if (Object.keys(sort).length > 0) {
+      pipeline.push({ $sort: sort })
+    }
+    const { limit, offset } = this._getLimitAndOffset(query)
+    pipeline.push({ $skip: offset })
+    pipeline.push({ $limit: limit })
+
+    const schemes = await this.model.aggregate(pipeline)
+    schemes.totalCount = await this._count(Scheme, [{ $match: mongoQuery }])
+
+    return schemes
+  }
+
+  async get(uri) {
+    return this.getScheme(uri)
+  }
+
+  async getScheme(identifierOrNotation) {
+    // TODO: Should we just throw an error 404 here?
+    if (!identifierOrNotation) {
+      return null
+    }
+    return await this.model.findOne({ $or: [{ uri: identifierOrNotation }, { identifier: identifierOrNotation }, { notation: new RegExp(`^${_.escapeRegExp(identifierOrNotation)}$`, "i") }] }).lean().exec()
+  }
+
+  async replaceSchemeProperties(entity, propertyPaths, ignoreError = true) {
+    await Promise.all(propertyPaths.map(async path => {
+      const uri = _.get(entity, `${path}.uri`)
+      let scheme
+      try {
+        scheme = await this.getScheme(uri)
+      } catch (error) {
+        if (!ignoreError) {
+          throw new InvalidBodyError(`Scheme with URI ${uri} not found. Only known schemes can be used.`)
+        }
+      }
+      if (scheme) {
+        _.set(entity, path, _.pick(scheme, ["uri", "notation"]))
+      } else if (!ignoreError) {
+        throw new InvalidBodyError(`Scheme with URI ${uri} not found. Only known schemes can be used.`)
+      }
+    }))
+  }
+
+  /**
+   * Return a Promise with an array of suggestions in JSKOS format.
+   */
+  async search(query) {
+    let search = query.query || query.search || ""
+    let results = await this._searchItems({ search })
+    const searchResults = results.slice(query.offset, query.offset + query.limit)
+    searchResults.totalCount = results.length
+    return searchResults
+  }
+
+  // Write endpoints start here
+
+  async updateItem({ body, existing, ...args }) {
+    let item = body
+
+    // Prepare
+    item = await this.prepareAndCheckItemForAction(item, "update")
+
+    // Override _id, uri, and created properties
+    item._id = existing._id
+    item.uri = existing.uri
+    item.created = existing.created
+
+    // Write item to database
+    const result = await this.model.replaceOne({ _id: item.uri }, item)
+    if (!result.acknowledged) {
+      throw new DatabaseAccessError()
+    }
+    if (!result.matchedCount) {
+      throw new EntityNotFoundError()
+    }
+
+    return (await this.postAdjustmentsForItems([item], args))[0]
+  }
+
+  async deleteItem({ uri, existing }) {
+    if (!uri) {
+      throw new MalformedRequestError()
+    }
+    if (existing.concepts.length) {
+      // Disallow deletion
+      // ? Which error type?
+      throw new MalformedRequestError(`Concept scheme ${uri} still has concepts in the database and therefore can't be deleted.`)
+    }
+    super.deleteItem({ existing })
+  }
+
+  /**
+   * Prepares and checks a concept scheme before inserting/updating:
+   * - validates object, throws error if it doesn't (create/update)
+   * - add `_id` property (create/update)
+   * - check if it exists, throws error if it doesn't (delete)
+   * - check if it has existing concepts in database, throws error if it has (delete)
+   *
+   * @param {Object} scheme concept scheme object
+   * @param {string} action one of "create", "update", and "delete"
+   * @returns {Object} prepared concept scheme
+   */
+  async prepareAndCheckItemForAction(scheme, action) {
+    if (!_.isObject(scheme)) {
+      throw new MalformedBodyError()
+    }
+    if (["create", "update"].includes(action)) {
+      if (!validate.scheme(scheme) || !scheme.uri) {
+        throw new InvalidBodyError()
+      }
+      scheme._id = scheme.uri
+      addKeywords(scheme)
+      if (action === "update") {
+        delete scheme.created
+      }
+    }
+    return scheme
+  }
+
+  /**
+   * Post-adjustments for concept schemes:
+   * - update `concepts` property
+   * - update `topConcepts` property
+   * - get updated concept scheme from database
+   *
+   * @param {[Object]} schemes array of concept schemes to be adjusted
+   * @param {Boolean} options.bulk indicates whether the adjustments are performaned as part of a bulk operation
+   * @returns {[Object]} array of adjusted concept schemes
+   */
+  async postAdjustmentsForItems(schemes, { bulk = false, setApi = false } = {}) {
+    // Get schemes from database instead
+    schemes = await this.model.find({ _id: { $in: schemes.map(s => s.uri) } }).lean().exec()
+    // First, set created field if necessary
+    await this.model.updateMany(
+      {
+        _id: { $in: schemes.map(s => s.uri) },
+        $or: [
+          { created: { $eq: null } }, { created: { $exists: false } },
+        ],
+      },
+      {
+        $set: {
+          created: (new Date()).toISOString(),
+        },
+      },
+    )
+    const result = []
+    for (let scheme of schemes) {
+      const hasTopConcepts = !!(await Concept.findOne({ $or: [scheme.uri].concat(scheme.identifier || []).map(uri => ({ "topConceptOf.uri": uri })) }))
+      const hasConcepts = hasTopConcepts || !!(await Concept.findOne({ $or: [scheme.uri].concat(scheme.identifier || []).map(uri => ({ "inScheme.uri": uri })) }))
+      const update = {
+        $set: {
+          concepts: hasConcepts ? [null] : [],
+          topConcepts: hasTopConcepts ? [null] : [],
+          modified: (new Date()).toISOString(),
+        },
+      }
+      if (setApi) {
+        let API = scheme.API || []
+        API = API.filter(entry => entry.url !== this.baseUrl)
+        if (hasConcepts) {
+          API = [
+            {
+              type: "http://bartoc.org/api-type/jskos",
+              url: this.baseUrl,
+            },
+          ].concat(API)
+        }
+        if (API.length) {
+          _.set(update, "$set.API", API)
+        } else {
+          _.set(update, "$unset.API", "")
+        }
+      }
+      if (bulk) {
+        delete update.$set.modified
+      }
+      await this.model.updateOne({ _id: scheme.uri }, update)
+      result.push(await this.model.findById(scheme.uri))
+    }
+    return result
+  }
+
+  async createIndexes() {
+    return this._createIndexes([
+      [{ uri: 1 }, {}],
+      [{ identifier: 1 }, {}],
+      [{ notation: 1 }, {}],
+      [{ created: 1 }, {}],
+      [{ modified: 1 }, {}],
+      [{ "subject.uri": 1 }, {}],
+      [{ "license.uri": 1 }, {}],
+      [{ "partOf.uri": 1 }, {}],
+      [{ _keywordsLabels: 1 }, {}],
+      [{ _keywordsPublisher: 1 }, {}],
+      // Add additional index for first entry which is used for sorting
+      [{ "_keywordsLabels.0": 1 }, {}],
+      [
+        {
+          _keywordsNotation: "text",
+          _keywordsLabels: "text",
+          _keywordsOther: "text",
+          _keywordsPublisher: "text",
+        },
+        {
+          name: "text",
+          default_language: "german",
+          weights: {
+            _keywordsNotation: 10,
+            _keywordsLabels: 6,
+            _keywordsOther: 3,
+            _keywordsPublisher: 3,
+          },
+        },
+      ]])
+  }
+}

package/services/validate.js

@@ -0,0 +1,39 @@
+import { validate } from "jskos-validate"
+import jskos from "jskos-tools"
+import { SchemeService } from "./schemes.js"
+const guessObjectType = jskos.guessObjectType
+
+import { AbstractService } from "./abstract.js"
+
+export class ValidateService extends AbstractService {
+
+  constructor(config) {
+    super(config)
+    this.schemeService = new SchemeService(config)
+  }
+
+  async validate(data, { unknownFields, type, knownSchemes = false } = {}) {
+    if (!Array.isArray(data)) {
+      data = [data]
+    }
+
+    // additional parameters (optional)
+    type = (guessObjectType(type, true) || "").toLowerCase()
+
+    const rememberSchemes = type ? null : []
+    if (knownSchemes) {
+      // Get schemes from schemeService
+      knownSchemes = await this.schemeService.queryItems({})
+      type = "concept"
+    }
+    const validator = type ? validate[type] : validate
+
+    const result = data.map(item => {
+      const result = validator(item, { unknownFields, knownSchemes, rememberSchemes })
+      return result ? true : validator.errors
+    })
+
+    return result
+  }
+
+}