aiiinotate 0.8.4 → 0.9.0

package/README.md

@@ -176,6 +176,20 @@ npm run migrate -- <command> <arguments?>
 npm run cli -- import <arguments>
 ```
 
+--- 
+
+## Test coverage
+
+aiiinotate is well tested: **over 90% test coverage** on all files ! 
+
+```
+ℹ ----------------------------------------------------------------------------------------
+ℹ file       | line % | branch % | funcs % | uncovered lines
+ℹ ----------------------------------------------------------------------------------------
+ℹ all files  |  90.02 |    79.43 |   78.73 |
+ℹ ----------------------------------------------------------------------------------------
+```
+
 ---
 
 ## License

package/cli/migrate.js

@@ -15,9 +15,6 @@ import { execSync } from "node:child_process"
 
 import { Command, Option, Argument } from "commander";
 
-import loadMongoClient from "#cli/utils/mongoClient.js";
-
-
 /** @typedef {"make"|"apply"|"revert"|"revert-all"} MigrateOpType */
 const allowedMigrateOp = ["make", "apply", "revert", "revert-all"];
 
@@ -109,17 +106,26 @@ async function action(command, migrationOp, options) {
 
 function makeMigrateCommand() {
   const migrationOpArg =
-    new Argument("<migration-op>", "name of migration operation").choices(allowedMigrateOp);
+    new Argument("<migration-op>", "name of migration operation")
+      .choices(allowedMigrateOp);
 
   const migrationNameOpt =
-    new Option("-n, --migration-name <name>", "name of migration (for 'make' argument)")
-      .makeOptionMandatory();
+    new Option("-n, --migration-name <name>", "name of migration (for 'make' argument)");
 
-  return new Command("migrate")
+  const command = new Command("migrate");
+  return command
     .description("run database migrations")
     .addArgument(migrationOpArg)
     .addOption(migrationNameOpt)
-    .action((migrationOp, options, command) => action(command, migrationOp, options))
+    .action((migrationOp, options, command) => {
+      if (
+        migrationOp == "make"
+        && (options.migrationName === undefined || options.migrationName === "")
+      ) {
+        command.error("migration operation \"apply\" requires option \"-n, --migration-name <name>\"", { exitCode: 1 });
+      }
+      action(command, migrationOp, options)
+    })
 }
 
 export default makeMigrateCommand;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiiinotate",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "a fast IIIF-compliant annotation server",
   "main": "./cli/index.js",
   "type": "module",
@@ -18,8 +18,7 @@
     "lint": "npx eslint --fix",
     "migrate": "npm run cli -- migrate",
     "update_version": "python3 scripts/update_version.py",
-    "get_version": "python3 scripts/get_version.py",
-    "ttt": "echo 'HELLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLO'"
+    "get_version": "python3 scripts/get_version.py"
   },
   "pre-commit": [
     "lint"

package/scripts/run.sh

@@ -27,7 +27,7 @@ case "$SCRIPT" in
         nodemon --watch ./src --exec "bash -c '$DOTENVX_BIN run -f $ENV_PATH -- node $ROOT_DIR/cli/index.js serve dev'";
         ;;
     test)
-        "$DOTENVX_BIN" run -f "$ENV_PATH" -- node --test --test-isolation=none
+        "$DOTENVX_BIN" run -f "$ENV_PATH" -- node --test --test-isolation=none --experimental-test-coverage
         ;;
     *)
         echo "Unknown run mode: $SCRIPT. Exiting...";

package/src/data/annotations/annotations2.js

@@ -7,7 +7,7 @@ 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 } from "#utils/utils.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";
 
@@ -62,7 +62,7 @@ class Annotations2 extends CollectionAbstract {
 
 
   /**
-   * @type {() => Promise<number>}
+   * @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
@@ -76,15 +76,28 @@ class Annotations2 extends CollectionAbstract {
    * @returns
    */
   #expandRouteAnnotationFilter(filterKey, filterVal) {
-    const allowedFilterKeys = [ "uri", "manifestShortId", "canvasUri" ];
+    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}'`)
     }
-    return  filterKey==="uri"
-      ? { "@id": filterVal }
-      : filterKey==="canvasUri"
-        ? { "on.full": filterVal }
-        : { "on.manifestShortId": filterVal };
+    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];
   }
 
   /**
@@ -412,16 +425,30 @@ class Annotations2 extends CollectionAbstract {
   // delete
 
   /**
-   * @param {AnnotationsDeleteKeyType} deleteKey - what deleteVal describes: an annotation's '@id', a manifest's URI...
-   * @param {string} deleteVal - deletion key
+   * @param {Object<string,string>} deleteFilter - filter for the annotations to delete
    * @returns {Promise<DeleteResponseType>}
    */
-  async deleteAnnotations(deleteKey, deleteVal) {
+  async deleteAnnotations(deleteFilter) {
+    const err = (message) => this.deleteError(`${this.funcName(this.deleteAnnotations)}: ${message}`);
     try {
-      const deleteFilter = this.#expandRouteAnnotationFilter(deleteKey, deleteVal);
-      return this.delete(deleteFilter);
+      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 this.deleteError(`${this.funcName(this.deleteAnnotations)}: ${err.message}`)
+      throw err(err.message);
     }
   }
 

package/src/data/manifests/manifests2.js

@@ -3,7 +3,7 @@ import fastifyPlugin from "fastify-plugin";
 import CollectionAbstract from "#data/collectionAbstract.js";
 import { getManifestShortId } from "#utils/iiif2Utils.js";
 import { formatInsertResponse } from "#utils/routeUtils.js";
-import { inspectObj, visibleLog, ajvCompile } from "#utils/utils.js";
+import { inspectObj, visibleLog, ajvCompile, memoize } from "#utils/utils.js";
 import { IIIF_PRESENTATION_2_CONTEXT } from "#utils/iiifUtils.js";
 import { BASE_URL } from "#constants";
 
@@ -46,6 +46,23 @@ class Manifests2 extends CollectionAbstract {
   /////////////////////////////////////////////
   // utils
 
+  /**
+   * fetch the array of canvasIds for a single manifest.
+   * since, in AIKON after a RegionExtraction, an annotation insert
+   * is done once per canvas, and for each annotation insert, we
+   * fetch the canvas index, we memoize the canvas list for each manifest URI
+   * to avoid multiplying database calls.
+   * @type {(string) => Promise<string[]>}
+   */
+  #memoizeGetManifestCanvasIds = memoize(async (manifestUri) => {
+    const doc = await this.collection
+      .findOne(
+        { "@id": manifestUri },
+        { projection: { canvasIds: 1, _id: 0 } }  // findOne is enough, there's only one manifest per URI
+      );
+    return doc?.canvasIds ?? [];
+  }, 60_000);
+
   /**
    * NOTE: PERFORMANCE: using AJV validation is MUCH FASTER than doing manual verifications (-25% execution time for the test suite)
    * @param {object} manifest
@@ -295,23 +312,18 @@ class Manifests2 extends CollectionAbstract {
    * @returns {Promise<number?>}
    */
   async getCanvasIdx(manifestUri, canvasUri) {
-    // NOTE: PERFORMANCE increases using `aggregate` with `$indexOfArray` to find the index of `canvasUri`: up to 30% faster execution of the app's test suite:
+    // old method without memoization.
     // - with `aggregate`, ~2800ms for the whole test suite to run.
     // - with a native `coll.findOne()` and then getting the canvas ID manually (`arr.indexOf`), ~4000ms for the whole test suite to run.
     // https://www.mongodb.com/docs/manual/aggregation/
     // https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexOfArray/
-    /**
-     * @type { { _id: MongoObjectId, index: number } | null }
-     * if `cursor.next() => null`, no document was found.
-     * otherwise the index is returned (-1 if `canvasIdx` was not found in the document)
-     */
-    const r = await this.collection.aggregate([
-      { $match: { "@id": manifestUri } },
-      { $project: { index: { $indexOfArray: ["$canvasIds", canvasUri] } } }
-    ]).next();
-    return r === null
-      ? undefined
-      : r.index !== -1 ? r.index : undefined;
+    // const r = await this.collection.aggregate([
+    //   { $match: { "@id": manifestUri } },
+    //   { $project: { index: { $indexOfArray: ["$canvasIds", canvasUri] } } }
+    // ]).next();
+    const r = await this.#memoizeGetManifestCanvasIds(manifestUri);
+    const index = r.indexOf(canvasUri);
+    return index !== -1 ? index : undefined
   }
 
   /**

package/src/data/routes.js

@@ -29,7 +29,7 @@ function commonRoutes(fastify, options, done) {
     routeDeleteSchema = fastify.schemasRoutes.getSchema("routeDelete"),
     responsePostSchema = makeResponsePostSchema(fastify),
     validatorRouteAnnotationDeleteSchema = ajvCompile(fastify.schemasResolver(
-      fastify.schemasRoutes.getSchema("routeAnnotationFilter")
+      fastify.schemasRoutes.getSchema("routeAnnotationDeleteFilter")
     )),
     validatorRouteManifestDeleteSchema = ajvCompile(fastify.schemasResolver(
       fastify.schemasRoutes.getSchema("routeManifestFilter")
@@ -147,7 +147,6 @@ function commonRoutes(fastify, options, done) {
               ? validatorRouteAnnotationDeleteSchema
               : validatorRouteManifestDeleteSchema,
           error = new Error(`Error validating DELETE route on collection '${collectionName}' with queryString '${inspectObj(query)}'`);
-
         if ( !validator(query) ) {
           returnError(request, reply, error, {}, 400);
         }
@@ -155,16 +154,16 @@ function commonRoutes(fastify, options, done) {
       }
     },
     async (request, reply) => {
-      const
-        { collectionName, iiifPresentationVersion } = request.params,
-        [ deleteKey, deleteVal ] = getFirstNonEmptyPair(request.query);
+      const { collectionName, iiifPresentationVersion } = request.params;
 
       try {
         if ( collectionName==="annotations" ) {
+          const deleteFilter = request.query;
           return iiifPresentationVersion === 2
-            ? await annotations2.deleteAnnotations(deleteKey, deleteVal)
+            ? await annotations2.deleteAnnotations(deleteFilter)
             : annotations3.notImplementedError();
         } else {
+          const [ deleteKey, deleteVal ] = getFirstNonEmptyPair(request.query);
           return iiifPresentationVersion === 2
             ? await manifests2.deleteManifest(deleteKey, deleteVal)
             : manifests3.notImplementedError();

package/src/data/routes.test.js

@@ -58,7 +58,10 @@ test("test common routes", async (t) => {
     await t.test("test preValidation hook for queryString validation", async (t) => {
       const data = [
         ["/manifests/2/delete?canvasUri=xxx", false],    // canvasUri is only allowed if `collectionName==="annotations"` => will fail.
-        ["/manifests/2/delete?manifestShortId=xxx", true]
+        ["/annotations/2/delete?tag=xxx", false],  // if using tag, manifestShortId must also be defined
+        ["/manifests/2/delete?tag=xxx&manifestShortId=xxx", false],  // tag is not allowed with `manifests`
+        ["/annotations/2/delete?tag=xxx&manifestShortId=xxx", true],
+        ["/manifests/2/delete?manifestShortId=xxx", true],
       ];
       for ( let i=0; i<data.length; i++ ) {
         const [url, expectSuccess] = data.at(i);
@@ -125,6 +128,33 @@ test("test common routes", async (t) => {
 
       await deletePipeline(true);
       await deletePipeline(false);
+      await fastify.emptyCollections();
+
+      await t.test("test route /annotations/:iiifPresentationVersion/delete with param 'tag'", async (t) => {
+        const
+          tags = ["tag1", "tag2", "tag3"],
+          // outputs one of the tags at random
+          selectTag = () => tags[Math.floor(Math.random() * 3)],
+          testTag = selectTag(),
+          // avoid changes to the global annotationList by cloning it.
+          annotationListCopy = structuredClone(annotationList),
+          // all annotations in the anno list are on the same manifest
+          manifestShortId = getManifestShortId(annotationList.resources[0].on);
+
+        annotationListCopy.resources = annotationList.resources.map((anno) => {
+          anno.resource = {
+            "@type": "oa:Tag",
+            "chars": selectTag()
+          }
+          return anno;
+        })
+        const expectedDeletedCount = annotationListCopy.resources.filter((anno) =>
+          anno.resource["@type"]==="oa:Tag"
+          && anno.resource["chars"]===testTag
+        ).length;
+        await injectTestAnnotations(fastify, t, annotationList);
+        await testDeleteRoute(t, `/annotations/2/delete?manifestShortId=${manifestShortId}&tag=${testTag}`, expectedDeletedCount);
+      })
     });
 
   })

package/src/schemas/schemasRoutes.js

@@ -165,6 +165,22 @@ function addSchemas(fastify, options, done) {
     ]
   })
 
+  // to delete an annotation by tag, you must also provide a manifestShortId (to avoid deleting all annotations with this tag in the entire db)
+  fastify.addSchema({
+    $id: makeSchemaUri("routeAnnotationFilterTag"),
+    type: "object",
+    required: ["tag", "manifestShortId"],
+    properties: {
+      manifestShortId: {
+        type: "string", description: "delete all annotations for a single manifest"
+      },
+      tag: {
+        type: "string", description: "delete allannotations for a single tag"
+      }
+    },
+    additionalProperties: false
+  })
+
   // for annotations: key-value pairs to filter a manifests collection by
   fastify.addSchema({
     $id: makeSchemaUri("routeAnnotationFilter"),
@@ -172,21 +188,33 @@ function addSchemas(fastify, options, done) {
       {
         type: "object",
         required: ["uri"],
-        properties: { uri: { type: "string", description: "delete the annotation with this '@id'" } }
+        properties: { uri: { type: "string", description: "delete the annotation with this '@id'" } },
+        additionalProperties: false
       },
       {
         type: "object",
         required: ["manifestShortId"],
-        properties: { manifestShortId: { type: "string", description: "delete all annotations for a single manifest" } }
+        properties: { manifestShortId: { type: "string", description: "delete all annotations for a single manifest" } },
+        additionalProperties: false
       },
       {
         type: "object",
         required: ["canvasUri"],
-        properties: { canvasUri: { type: "string", description: "delete all annotations for a single canvas" } }
+        properties: { canvasUri: { type: "string", description: "delete all annotations for a single canvas" } },
+        additionalProperties: false
       }
     ]
   })
 
+  // delete either by tag+manifestShortId, or by annotation URI, manifestShortId, canvasUri
+  fastify.addSchema({
+    $id: makeSchemaUri("routeAnnotationDeleteFilter"),
+    oneOf: [
+      { $ref: makeSchemaUri("routeAnnotationFilterTag") },
+      { $ref: makeSchemaUri("routeAnnotationFilter") },
+    ]
+  })
+
   ////////////////////////////////////////////////////////
   // MANIFESTS ROUTES
 
@@ -211,12 +239,14 @@ function addSchemas(fastify, options, done) {
       {
         type: "object",
         required: ["uri"],
-        properties: { uri: { type: "string" } }
+        properties: { uri: { type: "string" } },
+        additionalProperties: false
       },
       {
         type: "object",
         required: ["manifestShortId"],
-        properties: { manifestShortId: { type: "string" } }
+        properties: { manifestShortId: { type: "string" } },
+        additionalProperties: false
       }
     ]
   });