aiiinotate 0.2.0

package/src/data/utils/iiif2Utils.test.js

@@ -0,0 +1,98 @@
+import test from "node:test";
+
+import build from "#src/app.js";
+import { v4 as uuid4 } from "uuid";
+import { getManifestShortId, getCanvasShortId, getAnnotationTarget, makeTarget, makeAnnotationId } from "#utils/iiif2Utils.js";
+
+
+const
+  // hash-validating regex
+  hashRgx = /^\d+$/;
+
+test("test 'iiif2Utils' functions", async (t) => {
+  const
+    fastify = await build("test"),
+    { annotations2Valid, annotations2Invalid } = fastify.fileServer;
+
+  await fastify.ready();
+
+  t.after(() => fastify.close());
+
+  t.test("test 'getManifestShortId'", (t) => {
+    const
+      s1 = `manifest_${uuid4()}`,
+      s2 = `extra_${uuid4()}`,
+      // urls for which the function will manage to extract `s1`
+      urlOk = [
+        `http://www.example.com/examplePrefix/${s1}/manifest`,
+        `http://www.example.com/examplePrefix/${s1}/manifest.json`,
+        `http://www.example.com/examplePrefix/${s1}/sequence/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/canvas/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/annotation/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/list/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/range/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/layer/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/res/${s2}.png`,
+      ],
+      // urls for which `s1` won't be returned, and instead a hash will be returned
+      urlHash = [
+        `http://example.com/example/collection/${s2}`,
+        `http://example.com/${s1}`
+      ];
+
+    urlOk.map((url) =>
+      t.assert.strictEqual(getManifestShortId(url), s1));
+    urlHash.map((url) =>
+      t.assert.strictEqual(hashRgx.test(getManifestShortId(url)), true));
+  })
+
+  t.test("test 'getCanvasShortId'", (t) => {
+    const
+      s1 = `manifest_${uuid4()}`,
+      s2 = `canvas_${uuid4()}`,
+      urlOk = [
+        `http://www.example.com/examplePrefix/${s1}/canvas/${s2}`,
+        `http://www.example.com/examplePrefix/${s1}/canvas/${s2}.json`,
+
+      ],
+      urlHash = [
+        `http://example.com/example/${s2}`,
+        `http://example.com/${s2}`
+      ]
+    urlOk.map((url) =>
+      t.assert.strictEqual(getCanvasShortId(url), s2));
+    urlHash.map((url) =>
+      t.assert.strictEqual(hashRgx.test(getCanvasShortId(url)), true));
+
+  })
+
+  t.test("test 'getAnnotationTarget' and 'makeTarget'", async (t) => {
+    await Promise.all(
+      [getAnnotationTarget, makeTarget].map((func) =>
+
+        t.test(`test '${func.name}'`, (t) => {
+          annotations2Valid.map((annotation) =>
+            // to test for an error, it's necessary to create a new function:
+            // https://stackoverflow.com/a/6645586
+            t.assert.doesNotThrow(() => func(annotation)));
+          annotations2Invalid.map((annotation) =>
+            t.assert.throws(() => func(annotation), Error));
+        })
+
+      )
+    )
+  })
+
+  t.test("test 'makeAnnotationId'", (t) => {
+    // https://stackoverflow.com/a/6969486
+    const escapeRegExp = (string) =>
+      string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
+
+    const rgx = new RegExp(`^${escapeRegExp(process.env.APP_BASE_URL)}/data/2/[^(\\s|/)]+/annotation/[^\\.]+$`);
+    annotations2Valid.map((annotation) =>
+      t.assert.strictEqual(rgx.test(makeAnnotationId(annotation)), true));
+    annotations2Invalid.map((annotation) =>
+      t.assert.throws(() => makeAnnotationId(annotation)));
+  })
+
+})

package/src/data/utils/iiifUtils.js

@@ -0,0 +1,18 @@
+import { getHash } from "#utils/utils.js";
+
+const IIIF_PRESENTATION_2 = 2;
+const IIIF_PRESENTATION_3 = 3;
+const IIIF_SEARCH_1 = 1;
+const IIIF_SEARCH_2 = 2;
+const IIIF_PRESENTATION_2_CONTEXT = { "@context": "http://iiif.io/api/presentation/2/context.json" };
+const IIIF_PRESENTATION_3_CONTEXT = { "@context": "http://iiif.io/api/presentation/3/context.json" };
+
+
+export {
+  IIIF_PRESENTATION_2,
+  IIIF_PRESENTATION_3,
+  IIIF_SEARCH_1,
+  IIIF_SEARCH_2,
+  IIIF_PRESENTATION_2_CONTEXT,
+  IIIF_PRESENTATION_3_CONTEXT,
+}

package/src/data/utils/routeUtils.js

@@ -0,0 +1,109 @@
+import { inspectObj, isNonEmptyArray } from "#utils/utils.js";
+
+/** @typedef {import("mongodb").UpdateResult} MongoUpdateResultType */
+/** @typedef {import("#types").InsertResponseType} InsertResponseType */
+/** @typedef {import("#types").UpdateResponseType} UpdateResponseType */
+/** @typedef {import("#types").DeleteResponseType} DeleteResponseType */
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+
+/**
+ * functionnal alternative to `formatInsertResponse`, that aldready expects a formatted object
+ * @param {string[]?} insertedIds
+ * @param {string[]?} preExistingIds
+ * @param {string[]?} fetchErrorIds
+ * @param {string[]?} rejectedIds
+ * @returns {InsertResponseType}
+ */
+const formatInsertResponse = (insertedIds, preExistingIds, fetchErrorIds, rejectedIds) => {
+  const out = {
+    insertedCount: insertedIds?.length || 0,
+    insertedIds: insertedIds || [],
+  };
+  if ( fetchErrorIds?.length ) {
+    out.fetchErrorIds = fetchErrorIds;
+  }
+  if ( rejectedIds?.length ) {
+    out.rejectedIds = rejectedIds;
+  }
+  if ( preExistingIds?.length ) {
+    out.preExistingIds = preExistingIds;
+  };
+  return out;
+}
+
+/**
+ * @param {UpdateResponseType} mongoRes
+ * @returns {UpdateResponseType}
+ */
+const formatUpdateResponse = (mongoRes) => ({
+  matchedCount: mongoRes.matchedCount,
+  modifiedCount: mongoRes.modifiedCount,
+  upsertedCount: mongoRes.upsertedCount,
+  upsertedId: mongoRes.upsertedId
+});
+
+/**
+ * @param {DeleteResponseType} mongoRes
+ * @returns {DeleteResponseType}
+ */
+const formatDeleteResponse = (mongoRes) => ({
+  deletedCount: mongoRes.deletedCount
+});
+
+/**
+ * NOTE: fastify only implements top-level `$ref` in responses, using $ref in response schemas is not allowed.
+ * in turn, we can't use `{ $ref: makeSchemaUri }` and must resolve schemas instead.
+ * @param {FastifyInstanceType} fastify
+ * @param {object} okResponseSchema - expected response schema
+ */
+const makeResponseSchema = (fastify, okResponseSchema) => ({
+  200: okResponseSchema,
+  500: fastify.schemasRoutes.getSchema("routeResponseError")
+})
+
+const makeResponsePostSchema = (fastify) => makeResponseSchema(
+  fastify,
+  {
+    anyOf: [
+      fastify.schemasRoutes.getSchema("routeResponseInsert"),
+      fastify.schemasRoutes.getSchema("routeResponseUpdate"),
+      fastify.schemasRoutes.getSchema("routeResponseDelete"),
+    ]
+  }
+);
+
+/**
+ *
+ * @param {import("fastify").FastifyRequest} request
+ * @param {import("fastify").FastifyReply} reply
+ * @param {Error} err: the error we're returning
+ * @param {number} statusCode - the status code (defaults to 500)
+ * @param {any?} requestBody: the data on which the error occurred, for POST requests
+ */
+const returnError = (request, reply, err, requestBody={}, statusCode=500) => {
+  // otherwise, the error is not logged, bad for debugging.
+  console.error(inspectObj(err));
+
+  const error = {
+    message: `failed ${request.method.toLocaleUpperCase()} request because of error: ${err.message}`,
+    info: err.info || {},
+    method: request.method,
+    url: request.url
+  };
+  if ( requestBody !== undefined ) {
+    error.requestBody = requestBody
+  }
+  reply
+    .status(statusCode)
+    .header("Content-Type", "application/json; charset=utf-8")
+    .send(error);
+}
+
+export {
+  formatInsertResponse,
+  formatUpdateResponse,
+  formatDeleteResponse,
+  makeResponsePostSchema,
+  makeResponseSchema,
+  returnError
+}

package/src/data/utils/testUtils.js

@@ -0,0 +1,253 @@
+/**
+ * utilities and generally useful functions for tests.
+ */
+
+import { visibleLog } from "#utils/utils.js";
+
+/** @typedef {import("#types").NodeTestType} NodeTestType */
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+/** @typedef {import("#types").FastifyReplyType} FastifyReplyType */
+
+/**
+ * @param {NodeTestType} t
+ * @param {object} obj
+ * @param {Array} expectedKeys
+ * @returns {void}
+ */
+const assertObjectKeys = (t, obj, expectedKeys) =>
+  t.assert.deepStrictEqual(
+    Object.keys(obj).sort(),
+    expectedKeys.sort()
+  );
+
+/**
+ * insert responses MUST contain `insertedCount` and  MAY contain ["insertedIds", "preExistingIds", "fetchErrorIds", "rejectedIds"]
+ * @param {NodeTestType} t
+ * @param {object} obj
+ * @returns {void}
+ */
+const assertObjectKeysInsert = (t, obj) => {
+  t.assert.deepStrictEqual(
+    Object.keys(obj).every((k) => ["insertedCount", "insertedIds", "preExistingIds", "fetchErrorIds", "rejectedIds"].includes(k)),
+    true
+  );
+  t.assert.deepStrictEqual(
+    Object.keys(obj).includes("insertedCount"), true
+  )
+}
+
+/**
+ * @param {NodeTestType} t
+ * @param {object} obj
+ * @returns {void}
+ */
+const assertObjectKeysUpdate = (t, obj) =>
+  assertObjectKeys(t, obj, ["matchedCount", "modifiedCount", "upsertedCount", "upsertedId"]);
+
+/**
+ * @param {NodeTestType} t
+ * @param {object} obj
+ * @returns {void}
+ */
+const assertObjectKeysDelete = (t, obj) =>
+  assertObjectKeys(t, obj, ["deletedCount"]);
+
+/**
+ * @param {NodeTestType} t
+ * @param {object} obj
+ * @returns {void}
+ */
+const assertObjectKeysError = (t, obj) =>
+  assertObjectKeys(t, obj, ["message", "info", "method", "url", "requestBody"]);
+
+/**
+ * @param {NodeTestType} t
+ * @param {FastifyReplyType} r
+ * @param {number} expectedStatusCode
+ * @returns {void}
+ */
+const assertStatusCode = (t, r, expectedStatusCode) =>
+  t.assert.deepStrictEqual(r.statusCode, expectedStatusCode);
+
+/**
+ * @param {NodeTestType} t
+ * @param {FastifyReplyType} r
+ * @param {"insert"|"update"|"delete"|"error"} expectedResponse: keyword to define the response schema to test against.
+ * @returns {void}
+ */
+const assertResponseKeys = (t, r, expectedResponse) =>
+  expectedResponse === "insert"
+    ? assertObjectKeysInsert(t, JSON.parse(r.body))
+    : expectedResponse === "update"
+      ? assertObjectKeysUpdate(t, JSON.parse(r.body))
+      : expectedResponse === "delete"
+        ? assertObjectKeysDelete(t, JSON.parse(r.body))
+        : assertObjectKeysError(t, JSON.parse(r.body));
+
+/**
+ * @param {FastifyInstanceType} fastify
+ * @param {string} route
+ * @param {object} payload
+ * @returns {Promise<FastifyReplyType>}
+ */
+const injectPost = (fastify, route, payload) =>
+  fastify.inject({
+    method: "POST",
+    url: route,
+    payload: payload,
+  });
+
+/**
+ * @param {NodeTestType} t
+ * @param {FastifyReplyType} r
+ * @returns {void}
+ */
+const assertPostInvalidResponse = (t, r) => {
+  assertStatusCode(t, r, 500);
+  assertResponseKeys(t, r, "error");
+}
+
+/**
+ * @param {NodeTestType} t
+ * @param {FastifyReplyType} r
+ * @returns {void}
+ */
+const assertCreateValidResponse = (t, r) => {
+  assertStatusCode(t, r, 200);
+  assertResponseKeys(t, r, "insert");
+}
+
+/**
+ * @param {NodeTestType} t
+ * @param {FastifyReplyType} r
+ * @returns {void}
+ */
+const assertUpdateValidResponse = (t,r) => {
+  assertStatusCode(t, r, 200);
+  assertResponseKeys(t, r, "update");
+}
+
+/**
+ * @param {NodeTestType} t
+ * @param {FastifyReplyType} r
+ * @returns {void}
+ */
+const assertDeleteValidResponse = (t,r) => {
+  assertStatusCode(t, r, 200);
+  assertResponseKeys(t, r, "delete");
+}
+
+/**
+ * @param {NodeTestType} t
+ * @param {FastifyReplyType} r
+ * @param {number} expectedStatusCode
+ */
+const assertErrorValidResponse = (t, r, expectedStatusCode=500) => {
+  assertObjectKeysError(t, JSON.parse(r.body));
+  assertStatusCode(t, r, expectedStatusCode);
+};
+
+/**
+ * curried function to test  different operations with a post route.
+ * @param {FastifyInstanceType} fastify
+ */
+const testPostRouteCurry = (fastify) =>
+  /** @param {DataOperationsType} op */
+  (op) =>
+    /** @param {boolean} success - if `true` test that the query succeeds. else, test that it fails */
+    (success) =>
+      /**
+       * @param {NodeTestType} t
+       * @param {string} route: example: /annotations/2/createMany
+       * @param {object} payload
+       */
+      async (t, route, payload) => {
+        const
+          r = await injectPost(fastify, route, payload),
+          funcInvalid = assertPostInvalidResponse;
+
+        let funcValid;
+        if ( op==="insert" ) {
+          funcValid = assertCreateValidResponse;
+        } else if ( op==="update" ) {
+          funcValid = assertUpdateValidResponse;
+        } else {
+          throw new Error(`testPostRouteCurry: unimplemented value of 'op': '${op}'.`)
+        }
+
+        success
+          ? funcValid(t, r)
+          : funcInvalid(t, r);
+        return;
+      }
+
+const testDeleteRouteCurry =
+  /** @param {FastifyInstanceType} */
+  (fastify) =>
+  /**
+       * @param {NodeTestType} t
+       * @param {string} deleteRoute - route to delete data, with delete parameters embedded
+       * @param {number} expectedDeletedCount - number of documents that should be deleted
+       */
+    async (t, deleteRoute, expectedDeletedCount) => {
+      const r = await fastify.inject({
+        method: "DELETE",
+        url: deleteRoute
+      })
+      assertDeleteValidResponse(t, r);
+      t.assert.deepStrictEqual(JSON.parse(r.body).deletedCount, expectedDeletedCount);
+    }
+
+/**
+ * inject a manifest into the database for test purposes
+ * @param {FastifyInstanceType} fastify
+ * @param {NodeTestType} t
+ * @param {object} manifest - the manifest to insert
+ * @returns {Promise<Array<number, Array<string>>>}
+ */
+const injectTestManifest = async (fastify, t, manifest) => {
+  const
+    r = await injectPost(fastify, "/manifests/2/create", manifest),
+    { insertedCount, insertedIds } = JSON.parse(r.body);
+  t.assert.deepStrictEqual(insertedCount, 1);
+  return [ insertedCount, insertedIds ];
+}
+
+/**
+ * inject an annotationList into the database for test purposes
+ * @param {FastifyInstanceType} fastify
+ * @param {NodeTestType} t
+ * @param {object} annotationList - a IIIF 2.x annotation list
+ * @returns {Promise<Array<number, Array<string>>>}
+ */
+const injectTestAnnotations = async (fastify, t, annotationList) => {
+  const
+    r = await injectPost(fastify, "/annotations/2/createMany", annotationList),
+    rBody = JSON.parse(r.body),
+    expectedInsertedCount = annotationList.resources.length,
+    { insertedCount, insertedIds } = rBody;
+  t.assert.deepStrictEqual(insertedCount, expectedInsertedCount);
+  return [insertedCount, insertedIds];
+}
+
+
+export {
+  assertObjectKeys,
+  assertObjectKeysError,
+  assertObjectKeysInsert,
+  assertObjectKeysUpdate,
+  assertObjectKeysDelete,
+  assertStatusCode,
+  assertResponseKeys,
+  assertErrorValidResponse,
+  injectPost,
+  assertPostInvalidResponse,
+  assertCreateValidResponse,
+  assertUpdateValidResponse,
+  assertDeleteValidResponse,
+  testPostRouteCurry,
+  testDeleteRouteCurry,
+  injectTestManifest,
+  injectTestAnnotations
+}
+