@paulhectork/aiiinotate 0.12.0

package/src/data/annotations/annotations2.js

@@ -0,0 +1,681 @@
+/**
+ * IIIF presentation 2.1 annotation internals: convert incoming data, interct with the database, return data.
+ * exposes an `Annotations2` class that should contain everything you need to interact with the annotations2 collection.
+ */
+import fastifyPlugin from "fastify-plugin";
+
+import CollectionAbstract from "#data/collectionAbstract.js";
+import { STRICT_MODE } from "#constants";
+import { IIIF_PRESENTATION_2_CONTEXT } from "#utils/iiifUtils.js";
+import { ajvCompile, objectHasKey, isNullish, maybeToArray, visibleLog, memoize, getFirstNonEmptyPair } from "#utils/utils.js";
+import { getManifestShortId, makeTarget, makeAnnotationId, toAnnotationList, canvasUriToManifestUri } from "#utils/iiif2Utils.js";
+import { PAGE_SIZE } from "#constants";
+
+/** @typedef {import("mongodb").FindCursor} FindCursor */
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+/** @typedef {import("#types").MongoObjectId} MongoObjectId */
+/** @typedef {import("#types").MongoInsertResultType} MongoInsertResultType */
+/** @typedef {import("#types").MongoUpdateResultType} MongoUpdateResultType */
+/** @typedef {import("#types").MongoDeleteResultType} MongoDeleteResultType */
+/** @typedef {import("#types").InsertResponseType} InsertResponseType */
+/** @typedef {import("#types").UpdateResponseType} UpdateResponseType */
+/** @typedef {import("#types").DeleteResponseType} DeleteResponseType */
+/** @typedef {import("#types").DataOperationsType } DataOperationsType */
+/** @typedef {import("#types").AnnotationsDeleteKeyType } AnnotationsDeleteKeyType */
+/** @typedef {import("#types").Manifests2InstanceType} Manifests2InstanceType */
+/** @typedef {import("#types").AjvValidateFunctionType} AjvValidateFunctionType */
+
+/** @typedef {Annotations2} Annotations2InstanceType */
+
+// RECOMMENDED URI PATTERNS https://iiif.io/api/presentation/2.1/#a-summary-of-recommended-uri-patterns
+//
+// Collection 	             {scheme}://{host}/{prefix}/collection/{name}
+// Manifest 	               {scheme}://{host}/{prefix}/{identifier}/manifest
+// Sequence 	               {scheme}://{host}/{prefix}/{identifier}/sequence/{name}
+// Canvas 	                 {scheme}://{host}/{prefix}/{identifier}/canvas/{name}
+// Annotation (incl images)  {scheme}://{host}/{prefix}/{identifier}/annotation/{name}
+// AnnotationList            {scheme}://{host}/{prefix}/{identifier}/list/{name}
+// Range 	                   {scheme}://{host}/{prefix}/{identifier}/range/{name}
+// Layer 	                   {scheme}://{host}/{prefix}/{identifier}/layer/{name}
+// Content 	                 {scheme}://{host}/{prefix}/{identifier}/res/{name}.{format}
+
+/**
+ * @extends {CollectionAbstract}
+ */
+class Annotations2 extends CollectionAbstract {
+
+  /**
+   * @param {FastifyInstanceType} fastify
+   */
+  constructor(fastify) {
+    super(fastify, "annotations2");
+    /** @type {Manifests2InstanceType} */
+    this.manifestsPlugin = this.fastify.manifests2;
+    /** @type {AjvValidateFunctionType} */
+    this.validatorAnnotationList = ajvCompile(fastify.schemasResolver(
+      fastify.schemasPresentation2.getSchema("annotationList")
+    ));
+  }
+
+  ////////////////////////////////////////////////////////////////
+  // utils
+
+
+  /**
+   * @type {(object) => Promise<number>}
+   * cache the number of documents corresponding to a paginated query in a JS cache
+   * a simple cache avoids rerunning a count to get the total number of documents for each page of a paginated query
+   * see: https://dev.to/codewithjohnson/the-power-of-a-simple-cache-system-with-javascript-map-3j01
+   */
+  #memoizePaginationTotalCount = memoize((x) => this.collection.countDocuments(x), 2000);
+
+  /**
+   * expand a pair of `filterKey`, `filterVal` following the schema `routeAnnotationFilter` into a proper filter for the `annotations2` collection.
+   * @param {string} filterKey
+   * @param {string} filterVal
+   * @returns
+   */
+  #expandRouteAnnotationFilter(filterKey, filterVal) {
+    const allowedFilterKeys = [ "uri", "manifestShortId", "canvasUri", "tag" ];
+    if (!allowedFilterKeys.includes(filterKey)) {
+      throw new Error(`${this.funcname(this.#expandRouteAnnotationFilter)}: expected one of ${allowedFilterKeys} for param 'deleteKey', got '${filterKey}'`)
+    }
+    const map = {
+      uri: { "@id": filterVal },
+      canvasUri: { "on.full": filterVal },
+      manifestShortId: { "on.manifestShortId": filterVal },
+      tag: {
+        $and: [
+          {
+            // schema accepts both oa:Tag and Tag
+            $or: [
+              { "resource.@type": "oa:Tag" },
+              { "resource.@type": "Tag" }
+            ]
+          },
+          { "resource.chars": filterVal }
+        ]
+      }
+    }
+    return map[filterKey];
+  }
+
+  /**
+   * clean the body of an annotation (annotation.resource).
+   * if `annotation.resource` is an array (there are several bodies associated to that annotation), this function must be called on each item of the array
+   * @param {object} resource
+   * @returns {object | null} - the resource, or `null` if the resource is either an empty Embedded Textual Body or has no `@id`
+   */
+  #cleanAnnotationResource(resource) {
+    if (resource) {
+      // 1) uniformize embedded textual body keys
+      // OA allows `cnt:ContentAsText` or `dctypes:Text` for Embedded Textual Bodies, IIIF only uses `dctypes:Text`
+      resource["@type"] =
+        resource["@type"] === "cnt:ContentAsText"
+          ? "dctypes:Text"
+          : resource["@type"];
+
+      // OA stores Textual Body content in `cnt:chars`, IIIF uses `chars`. `value` is sometimes also used
+      resource.chars = resource.value || resource["cnt:chars"] || resource.chars;  // may be undefined
+      [ "value", "cnt:chars" ].map((k) => {
+        if (Object.keys(resource).includes(k)) {
+          delete resource[k];
+        }
+      })
+
+      // 2) return `null` if resource is empty. a body is empty if
+      //  - it's got no `@id` (=> it's not a referenced textaul body)
+      //  - it's not an Embedded Textual Body, or it's an empty Embedded Textual Body.
+      // see: https://github.com/Aikon-platform/aiiinotate/blob/dev/docs/specifications/0_w3c_open_annotations.md#embedded-textual-body-etb
+      const
+        hasTextualBody = objectHasKey(resource, "chars"),
+        emptyBody = isNullish(resource.chars) || resource.chars === "<p></p>";
+      if (isNullish(resource["@id"]) && (emptyBody || !hasTextualBody)) {
+        return null
+      }
+    }
+    return resource;
+  }
+
+  /**
+   * clean an annotation before saving it to database.
+   * some of the work consists of translating what is defined by the OpenAnnotations standard to what is actually used by IIIF annotations.
+   * if `update`, some cleaning will be skipped (especially the redefinition of "@id"), otherwise updates would fail.
+   *
+   * @param {{ annotation: object, update: boolean, throwOnXywhError: boolean }} annotation
+   * @returns {object}
+   */
+  async #cleanAnnotation({
+    annotation,
+    update=false,
+    throwOnXywhError=STRICT_MODE
+  }) {
+    // 1) extract ids and targets. convert the target to an array.
+    // we assume that all values of `annotationTargetArray` point to the same manifest => `manifestShortId` is extracted from the 1st target
+    const
+      annotationTargetArray = await makeTarget(annotation),
+      manifestShortId = annotationTargetArray[0].manifestShortId;
+
+    if (throwOnXywhError && annotationTargetArray[0]?.xywh.some(x => isNaN(x))) {
+      throw this.insertError("annotations2.#cleanAnnotation: could not extract bounding box for annotation target", annotation.on);
+    }
+
+    // in updates, "@id" has aldready been extracted
+    if (!update) {
+      annotation["@id"] = makeAnnotationId(annotation, manifestShortId);
+    }
+    annotation["@context"] = IIIF_PRESENTATION_2_CONTEXT["@context"];
+    annotation.on = annotationTargetArray;
+
+    // 2) process motivations.
+    // - motivations are an array of strings
+    // - open annotation specifies that motivations should be described by the `oa:Motivation`, while IIIF 2.1 examples uses the `motivation` field => uniformizwe
+    // - all values must be `sc:painting` or prefixed by `oa:`: IIIF presentation API indicates that the only allowed values are open annotation values (prefixed by `oa:`) or `sc:painting`.
+    if (objectHasKey(annotation, "oa:Motivation")) {
+      annotation.motivation = annotation["oa:Motivation"];
+      delete annotation["oa:motivation"];
+    }
+    annotation.motivation =
+      maybeToArray(annotation.motivation || [])
+        .map(String)
+        .map((motiv) =>
+          motiv.startsWith("oa:") || motiv.startsWith("sc:")
+            ? motiv
+            : `oa:${motiv}`
+        );
+
+    // 3) process the resource. Resource can be either undefined, an array of objects or a single object. process all objects and, if there's no resource content, delete `annotation.resource`.
+    let resource = annotation.resource || undefined;
+    if (resource) {
+      resource =
+        Array.isArray(resource)
+          ? resource.map((r) => this.#cleanAnnotationResource(r)).filter((r) => r !== null)
+          : this.#cleanAnnotationResource(resource);
+    }
+    if (resource === null || resource === undefined || (Array.isArray(resource) && !resource.length)) {
+      delete annotation.resource;
+    } else {
+      annotation.resource = resource;
+    }
+    return annotation;
+  }
+
+  /**
+   * take an annotationList, clean it and return it as a array of annotations.
+   * see: https://iiif.io/api/presentation/2.1/#annotation-list
+   * @param {object} annotationList
+   * @param {boolean} throwOnXywhError
+   * @returns {Promise<object[]>}
+   */
+  async #cleanAnnotationList(annotationList, throwOnXywhError=STRICT_MODE) {
+    // NOTE: if `this.#cleanAnnotationList` can only be accessed from annotations routes, then this check is useless (has aldready been performed).
+    if (this.validatorAnnotationList(annotationList)) {
+      this.errorNoAction("Annotations2.#cleanAnnotationList: could not recognize AnnotationList. see: https://iiif.io/api/presentation/2.1/#annotation-list.", annotationList)
+    }
+    return await Promise.all(
+      annotationList.resources.map(async (ressource) =>
+        await this.#cleanAnnotation({ annotation: ressource, throwOnXywhError })
+      )
+    )
+  }
+
+  /**
+   * after attempting to insert a manifests, update a single target of an annotation :
+   * 1. set manifestUri to `undefined` if manifest insertion failed
+   * 2. fetch target canvas index to populate canvasIdx
+   * @param {object} target: a single value of the annotation.on array
+   * @param {string[]} insertedManifestIds
+   * @returns {Promise<object>} the updated target
+   */
+  async #updateTargetPostManifestInsert(target, insertedManifestIds) {
+    // set manifestUri to `undefined` if manifest insertion failed.
+    const updateManifestUri = (manifestUri) =>
+      insertedManifestIds.find((x) => x === manifestUri)
+        ? manifestUri
+        : undefined;
+
+    // if manifest insertion worked (manifestUri) is not undefined, fetch the canvas index based on the canvas' URI
+    const setCanvasIdx = async (manifestUri, canvasUri) =>
+      manifestUri
+        ? await this.manifestsPlugin.getCanvasIdx(manifestUri, canvasUri)
+        : undefined;
+
+    target.manifestUri = updateManifestUri(target.manifestUri);
+    target.canvasIdx = await setCanvasIdx(target.manifestUri, target.full);
+    return target;
+  }
+
+  /**
+   * after attempting to insert manifests, update a single annotation
+   * @param {object} annotation
+   * @param {string[]} insertedManifestIds
+   * @param {boolean} throwOnCanvasIndexError
+   * @returns {Promise<object>} the updated annotation
+   */
+  async #updateAnnotationPostManifestInsert(annotation, insertedManifestIds, throwOnCanvasIndexError) {
+    /** @type {object[]} */
+    let targetArray = annotation.on;
+    targetArray = await Promise.all(
+      targetArray.map(async (target) =>
+        await this.#updateTargetPostManifestInsert(target, insertedManifestIds))
+    )
+    if (
+      throwOnCanvasIndexError
+      && targetArray.some((target) => target.canvasIdx === undefined)
+    ) {
+      const canvasUris = targetArray.map((target) => target.full)
+      throw this.insertError(`${this.funcName(this.#insertManifestsAndGetCanvasIdx)}: could not get canvasIdx for annotation (canvas URI: ${canvasUris})`);
+    }
+    annotation.on = targetArray;
+    return annotation;
+  }
+
+  /**
+   * handle all side effects on the `manifests2` collection. this does 2 things:
+   * - insert all manifests referenced by `annotationData`, and set a key `on.manifestId` on all annotations.
+   * - set a key `canvasIdx` in all values of `annotation.on`, containing the position of the annotation's target canvas in the manifest,
+   *    (or undefined if the manifest or canvas were not found).
+   * @param {object|object[]} annotationData - an annotation, or array of annotations.
+   * @param {boolean} throwOnCanvasIndexError - if canvasIdx can't be found, raise an error.
+   */
+  async #insertManifestsAndGetCanvasIdx(annotationData, throwOnCanvasIndexError=STRICT_MODE) {
+    // NOTE: instead of propagating `throwOnCanvasIndexError` to `insertManifestsFromUriArray`, we could just check if `insertResponse.fetchErrorIds.length > 0` and return an error then.
+    // convert objects to array to get a uniform interface.
+    let converted;
+    [ annotationData, converted ] = maybeToArray(annotationData, true);
+
+    // 1. get all distinct manifest URIs
+    const manifestUris = [];
+    annotationData.map((ann) => ann.on.map((target) => {
+      if (target.manifestUri != null && !manifestUris.includes(target.manifestUri)) {
+        manifestUris.push(target.manifestUri);
+      }
+    }));
+
+    // 2. insert the manifests
+    const
+      insertResponse = await this.manifestsPlugin.insertManifestsFromUriArray(manifestUris, throwOnCanvasIndexError),
+      /** @type {string[]} concatenation of ids of newly inserted manifests and previously inserted manifests. */
+      insertedManifestIds = insertResponse.insertedIds.concat(insertResponse.preExistingIds || []);
+
+    // 3. update annotations with info on manifest and canvas.
+    annotationData = await Promise.all(
+      annotationData.map(async (annotation) =>
+        await this.#updateAnnotationPostManifestInsert(annotation, insertedManifestIds, throwOnCanvasIndexError)
+      )
+    );
+
+    // retroconvert array to single object, if single object was converted.
+    return converted
+      ? annotationData[0]
+      : annotationData;
+  }
+
+  /**
+   * taking a filter document `queryFilter`, return an annotationList with paginated results
+   *
+   * params:
+   * - queryUrl: the `@id` of the annotationList.
+   *    MUST be an URL to a route that sjupports pagination, in order to set `prev` and `next` in the annotationList.
+   * - queryFilter: the filter to apply to the collection
+   * - page: current page number
+   * - pageSize: number of annotations per page
+   * - label: title of the AnnotationList.
+   *
+   * returns: the paginated AnnotationList as a promise
+   *
+   * NOTE: other/more performant forms of pagination than offset: https://medium.com/mongodb/mongodb-pagination-offset-based-vs-keyset-vs-pre-generated-result-pages-4177e05d88ec
+   *
+   * @param {{
+   *  queryUrl: string,
+   *  queryFilter: object,
+   *  page: number,
+   *  pageSize: number,
+   *  label: string?
+   * }}
+   * @returns {Promise<object>} - paginated annotation list
+   */
+  async #paginate({
+    queryUrl,
+    queryFilter,
+    page=1,
+    pageSize=PAGE_SIZE,
+    label=undefined
+  }) {
+    const totalCount = await this.#memoizePaginationTotalCount(queryFilter);
+
+    const skip = Math.max((page-1) * pageSize, 0);  // number of queried items up until the previous page included.
+    const cursor = await this.find(queryFilter, {}, true);
+    const annotations = await cursor
+      .sort({ "@id": 1 })
+      .skip(skip)
+      .limit(pageSize)
+      .toArray();
+
+    const hasNext = page * pageSize <= totalCount;
+
+    return toAnnotationList({
+      resources: annotations,
+      annotationListId: queryUrl,
+      page: page,
+      hasNext: hasNext,
+      label: label
+    });
+  }
+
+  ////////////////////////////////////////////////////////////////
+  // insert / updates
+
+  /**
+   * validate and insert a single annotation.
+   *
+   * about `throwOnCanvasIndexError`:
+   * when inserting, aiiinotate attempts to fetch the target manifest of an annotation and to add the canvas number of the annotation to `annotation.on`.
+   * this may fail for a number of reasons (manifest URL and JSON structure, server storing the manifest is inaccessible...). if `throwOnCanvasIndexError`, it will raise.
+   *
+   * about `throwOnXywhError`: XYWH bounding-box extraction of an annotation is not supported for all selectors (see: `selectorToXywh()`).
+   * by default, no error is raised if a bounding box can't be extracted.
+   * if `throwOnXywhError`, an error will be thrown. this is for controlled environments where you know exactly what you'll be sending aiiinotate and must rely on `xywh`
+   *
+   * @param {object} annotation
+   * @param {boolean} throwOnCanvasIndexError
+   * @param {boolean} throwOnXywhError
+   * @returns {Promise<InsertResponseType>}
+   */
+  async insertAnnotation(annotation, throwOnCanvasIndexError=STRICT_MODE, throwOnXywhError=STRICT_MODE) {
+    annotation = await this.#cleanAnnotation({ annotation, update: false, throwOnXywhError });
+    annotation = await this.#insertManifestsAndGetCanvasIdx(annotation, throwOnCanvasIndexError);
+    return this.insertOne(annotation);
+  }
+
+  /**
+   * TODO: handle side effects when changing `annotation.on`: changes that can affect `manifestShortId`, `manifestUri` and `canvasIdx`
+   *    (for example, updating `annotation.on.full` would ask to change `canvasIdx`).
+   * @param {object} annotation
+   * @param {boolean?} throwOnCanvasIndexError
+   * @param {boolean?} throwOnXywhError
+   * @returns {Promise<UpdateResponseType>}
+   */
+  async updateAnnotation(annotation, throwOnCanvasIndexError=STRICT_MODE, throwOnXywhError=STRICT_MODE) {
+    // necessary: on insert, the `@id` received is modified by `this.#cleanAnnotationList`.
+    annotation = await this.#cleanAnnotation({ annotation, update: true, throwOnXywhError });
+    // necessary:
+    //  1. handle changes to target canvas' manifest
+    //  2. when updating an annotation in MAE, the non-standard fields in the annotation are lost:
+    //    `canvasIdx`, `manifestUri`, `manifestShortId` are not serialized/deserialized in MAE.
+    annotation = await this.#insertManifestsAndGetCanvasIdx(annotation, throwOnCanvasIndexError);
+    const
+      query = { "@id": annotation["@id"] },
+      update = { $set: annotation };
+    return this.updateOne(query, update);
+  }
+
+  /**
+   * validate and insert annotations from an annotation list.
+   *
+   * about `throwOnCanvasIndexError`:
+   * when inserting, aiiinotate attempts to fetch the target manifest of an annotation and to add the canvas number of the annotation to `annotation.on`.
+   * this may fail for a number of reasons (manifest URL and JSON structure, server storing the manifest is inaccessible...). if `throwOnCanvasIndexError`, it will raise.
+   *
+   * about `throwOnXywhError`:
+   * we try to calculate the bounding box of an annotation. this is only supported for FragmentSelectors and SvgSelectors, and will fail otherwise
+   * => if `throwOnXywhError`, throw if there is an error calculating the bounding box.
+   *
+   * @param {object} annotationList
+   * @param {boolean?} throwOnCanvasIndexError
+   * @param {boolean?} throwOnXywhError
+   * @returns {Promise<InsertResponseType>}
+   */
+  async insertAnnotationList(annotationList, throwOnCanvasIndexError=STRICT_MODE, throwOnXywhError=STRICT_MODE) {
+    let annotationArray;
+    annotationArray = await this.#cleanAnnotationList(annotationList, throwOnXywhError);
+    annotationArray = await this.#insertManifestsAndGetCanvasIdx(annotationArray, throwOnCanvasIndexError);
+    return this.insertMany(annotationArray);
+  }
+
+  ////////////////////////////////////////////////////////////////
+  // delete
+
+  /**
+   * @param {Object<string,string>} deleteFilter - filter for the annotations to delete
+   * @returns {Promise<DeleteResponseType>}
+   */
+  async deleteAnnotations(deleteFilter) {
+    const err = (message) => this.deleteError(`${this.funcName(this.deleteAnnotations)}: ${message}`);
+    try {
+      let expandedDeleteFilter;
+      if (Object.keys(deleteFilter).includes("tag")) {
+        // should be validated by the route's JSONSchema, but just in case.
+        if (! Object.keys(deleteFilter).includes("manifestShortId")) {
+          throw err("Cannot delete by \"tag\" without also filtering by \"manifestShortId\" !")
+        }
+        const expand = (k) => this.#expandRouteAnnotationFilter(k, deleteFilter[k]);
+        expandedDeleteFilter = {
+          ...expand("tag"),
+          ...expand("manifestShortId")
+        }
+      } else {
+        const [ deleteKey, deleteVal ] = getFirstNonEmptyPair(deleteFilter);
+        expandedDeleteFilter = this.#expandRouteAnnotationFilter(deleteKey, deleteVal);
+      }
+      return this.delete(expandedDeleteFilter);
+    } catch (err) {
+      throw err(err.message);
+    }
+  }
+
+  ////////////////////////////////////////////////////////////////
+  // get
+
+  /**
+   * find documents based on a `queryObj` and project them to `projectionObj`.
+   *
+   * about projection: 0 removes the fields from the response, 1 incldes it (but exclude all others)
+   * see: https://www.mongodb.com/docs/drivers/node/current/crud/query/project/#std-label-node-project
+   *      https://stackoverflow.com/questions/74447979/mongoservererror-cannot-do-exclusion-on-field-date-in-inclusion-projection
+   * @param {object} queryObj - the filter document
+   * @param {object?} projectionObj - extra projection fields to tailor the reponse format
+   * @param {boolean} asCursor - return a cursor instead of an array of results
+   * @returns {Promise<object[] | FindCursor>}
+   */
+  async find(queryObj, projectionObj={}, asCursor=false) {
+    // 1. construct the final projection object, knowing that we can't mix exclusive and inclusive projectin.
+    // presence of `_id` will not cause projections to fail => remove it from values.
+    const projectionValues =
+      Object.entries(projectionObj)
+        .filter(([ k,v ]) => k !== "_id")
+        .map(([ k,v ]) => v);
+
+    // if there are projection values defined and if they're not 0 or 1, then they're invalid => throw
+    if (projectionValues.length && projectionValues.find((x) => ![ 0,1 ].includes(x))) {
+      throw this.readError(`Annotations2.find: only allowed values for projection are 0 and 1. got: ${[ ...new Set(projectionValues) ]}`)
+    }
+    // mongo projection can be either inclusive (define only fields that will be included) or negative (define only fields that will be excluded), but not a mix of the 2. if you have more than 1 distinct values, you mixed inclusion and exclusion => throw
+    const distinctProjectionValues = [ ...new Set(projectionValues) ]
+    if (distinctProjectionValues.length > 1) {
+      throw this.readError(`Annotations2.find: can't mix insertion and exclusion projection in 'projectionObj'. all values must be either 0 or 1. got: ${distinctProjectionValues}`, projectionObj)
+    }
+    // negative projection: all fields will be included except for those specified.
+    // in this case, negate other fields that we don't ant exposed.
+    // in case of positive projection, no specific processing is required: only the explicitly required fields are included.
+    // in all cases, `_id` should not be included unless we explicitly ask for it.
+    projectionObj._id = projectionObj._id || 0;
+    if (distinctProjectionValues[0] === 0) {
+      projectionObj["on.manifestShortId"] = projectionObj["on.manifestShortId"] || 0;
+    }
+
+    // 2. find, project and return
+    const cursor = this.collection.find(queryObj, { projection: projectionObj });
+    if (!asCursor) {
+      return cursor.toArray()
+    } else {
+      return cursor;
+    };
+  }
+
+  /**
+   * implementation of the IIIF Search API 1.0.
+   * function arguments have been validated by JSONSchemas at route-level so they're clean.
+   *
+   * parameters:
+   * - queryUrl - the request URL (/search-api...)
+   * - manifestShortId - the manifest's identifier
+   * - q: query string (content to search for in annotations)
+   * - motivation: filter by annotation motivation
+   * - canvasMin - minimum value of `on.canvasIdx`, inclusive
+   * - canvasMax - maximum value of `on.canvasIdx`, inclusive
+   * - onlyIds - return only the @ids of matched annotations instead of the entire annotations
+   *
+   * NOTE:
+   *  - only `motivation` and `q` search params are implemented
+   *  - to increase search execution speed, ONLY EXACT STRING MACHES are
+   *    implemented for `q` and `motivation` (in the IIIF specs, you can supply
+   *    multiple space-separated values and the server should return all partial
+   *    matches to any of those strings.)
+   * - non-standard `canvasMin`, `canvasMax` and `onlyIds` parameters are implemented
+   *
+   * see:
+   *  https://iiif.io/api/search/1.0/
+   *  https://github.com/Aikon-platform/aiiinotate/blob/dev/docs/specifications/4_search_api.md
+   *
+   * @param {{
+   *   queryUrl: string,
+   *   manifestShortId: string,
+   *   q: string?,
+   *   motivation: ("painting"|"non-painting"|"commenting"|"describing"|"tagging"|"linking")?,
+   *   canvasMin: number?,
+   *   canvasMax: number?,
+   *   onlyIds: boolean
+   *   page: number
+   *   pageSize: number
+   * }}
+   * @returns {object} annotationList containing results
+   */
+  async search({
+    queryUrl,
+    manifestShortId,
+    q,
+    motivation=undefined,
+    canvasMin=undefined,
+    canvasMax=undefined,
+    onlyIds=false,
+    page=1,
+    pageSize=PAGE_SIZE
+  }) {
+    const
+      filtersBase = { "on.manifestShortId": manifestShortId },
+      filtersExtra = { $and: [] };
+
+    // expand query parameters
+    if (q) {
+      filtersExtra.$and.push({
+        $or: [
+          { "@id": q },
+          { "resource.@id": q },
+          { "resource.chars": q }
+        ]
+      });
+    };
+    if (motivation) {
+      filtersExtra.$and.push(
+        motivation === "non-painting"
+          ? { motivation: { $ne: "sc:painting" } }
+          : motivation === "painting"
+            ? { motivation: "sc:painting" }
+            : { motivation: `oa:${motivation}` }
+      );
+    };
+    if (!isNaN(canvasMin)) {
+      // if canvasMax is undefined, then search for canvasIdx===canvasMin
+      if (!canvasMax) {
+        filtersExtra.$and.push({ "on.canvasIdx": canvasMin })
+      // if canvasMin and canvasMax, canvasIdx must be in [canvasMin, canvasMax] (inclusive).
+      } else {
+        filtersExtra.$and.push({
+          $and: [
+            { "on.canvasIdx": { $gte: canvasMin } },
+            { "on.canvasIdx": { $lte: canvasMax } }
+          ]
+        })
+      }
+    }
+    const queryFilter =
+      filtersExtra.$and.length
+        ? { ...filtersBase, ...filtersExtra }
+        : filtersBase;
+
+    if (!onlyIds) {
+      return await this.#paginate({
+        queryUrl,
+        queryFilter,
+        page,
+        pageSize,
+        label: `Paginated annotation List (page: ${page}, ${pageSize} items per page)`
+      })
+    } else {
+      // NOTE: there is no pagination if `onlyIds` is true
+      return (await this.find(queryFilter, { "@id": 1 }))
+        .map((ann) => ann["@id"]);
+    }
+  }
+
+  /**
+   * find all annotations whose target (`on.full`) is `canvasUri`.
+   * @param {{
+   *   queryUrl: string,
+   *   canvasUri: string,
+   *   page: Number,
+   *   pageSize: Number
+   * }} canvasUri
+   * @returns {AnnotationList}
+   */
+  async findByCanvasUri({
+    queryUrl,
+    canvasUri,
+    page=1,
+    pageSize=PAGE_SIZE
+  }) {
+    return this.#paginate({
+      queryUrl,
+      queryFilter: { "on.full": canvasUri },
+      label: `annotations targeting canvas ${canvasUri}`,
+      page,
+      pageSize
+    });
+  }
+
+  /**
+   * find an annotation by its "@id"
+   * @param {string} annotationUri
+   * @returns {Promise<object>}  the annotation, or `{}` if none was found
+   */
+  async findById(annotationUri) {
+    return this.collection.findOne({ "@id": annotationUri })
+  }
+
+  /**
+   * count number of annotations.
+   * @param {string} filterKey
+   * @param {string} filterVal
+   * @returns
+   */
+  async count(filterKey, filterVal) {
+    try {
+      const
+        countFilter = this.#expandRouteAnnotationFilter(filterKey, filterVal),
+        count = await this.collection.countDocuments(countFilter);
+      return { count: count }
+    } catch (err) {
+      throw this.readError(`${this.funcName(this.count)}: ${err.message}`)
+    }
+  }
+
+}
+
+export default fastifyPlugin((fastify, options, done) => {
+  fastify.decorate("annotations2", new Annotations2(fastify));
+  done();
+}, {
+  name: "annotations2",
+  dependencies: [ "manifests2" ]
+})