aiiinotate 0.10.0 → 0.10.1

package/README.md

@@ -180,7 +180,7 @@ npm run cli -- import <arguments>
 
 ## Test coverage
 
-aiiinotate is well tested: **over 90% test coverage** on all files ! 
+aiiinotate is well tested: **~90% test coverage** on all files ! 
 
 ```
 ℹ ----------------------------------------------------------------------------------------

package/docs/cli.md

@@ -64,17 +64,20 @@ aiiinotate migrate revert-all
 
 ## `import`: import data
 
+The CLI can be used to import IIIF annotations or to index IIIF manifests in aiiinotate.
+
 ```bash
 # in prod
-aiiinotate import -i 2 -f <path/to/import/file.txt>
+aiiinotate import <manifests|annotations> -i 2 -f <path/to/import/file.txt>
 ```
 
 Where:
+- `<manifests|annotations>` is the kind of data to import: manifests or annotations
 - `-i` `--iiif-version` (`2|3`) is the IIIF Presentation API version of the data to import:
-    - if `-i 3`, we import IIIF presentation 3.x annotations
-    - if `-i 2`, we import IIIF presentation 2.x annotations
+    - if `-i 3`, we import IIIF presentation 3.x data
+    - if `-i 2`, we import IIIF presentation 2.x data
 - `-f --file` is a relative or absolute path the the import file. This import file:
-    - contains a list of paths to annotation lists or annotation pages
+    - contains a list of paths to annotation lists, annotation pages or manifests
     - with 1 path per line
     - paths can be relative or absolute
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiiinotate",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "a fast IIIF-compliant annotation server",
   "main": "./cli/index.js",
   "type": "module",

package/src/data/annotations/annotations2.js

@@ -345,7 +345,6 @@ class Annotations2 extends CollectionAbstract {
     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 })

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, memoize } from "#utils/utils.js";
+import { inspectObj, visibleLog, ajvCompile, memoize, objectHasKey } from "#utils/utils.js";
 import { IIIF_PRESENTATION_2_CONTEXT } from "#utils/iiifUtils.js";
 import { PUBLIC_URL } from "#constants";
 
@@ -70,7 +70,11 @@ class Manifests2 extends CollectionAbstract {
    */
   #validateManifest(manifest) {
     if (!this.validatorManifest(manifest)) {
-      throw this.insertError("validateManifest: invalid manifest structure", manifest);
+      let info = {};
+      if (objectHasKey(manifest, "@id")) {
+        info = { "@id": manifest["@id"] };
+      }
+      throw this.insertError("validateManifest: invalid manifest structure", info);
     }
   }
 

package/src/utils/utils.js

@@ -282,41 +282,67 @@ const recursiveSort = (x) => {
 }
 
 /**
- * Map cache with a timeout: after `timeout` ms have passed, clears the cache of the key `n`.
- * if `timeout` is negative, the cache will never be cleared of `n`.
+ * Map cache with a timeout and a max size:
+ * - after `timeout` ms have passed, clears the cache of the key `n`.
+ * - to avoid the cache to grow unbounded, we define a max size after which
+ *    we delete the greatest items in the cache.
  *
  * NOTE: LIMITATIONS:
- * - `memoize` converts `fn` to an async function to work with both sync/async patterns, remember to await !
- * - `fn` should accept a single agument `n`
- * - `n` should be JSON-stringify-able: a primitive, an array, or an object, but not a function, a class or class instance
+ * - `memoize` converts `fn` to an async function to work with both
+ *    sync/async patterns, remember to await !
+ * - the args applied to `fn` must be JSON-stringify-able: a primitive,
+ *    an array, or an object, but not a function, a class or class instance
  *
  * adapted from: https://dev.to/codewithjohnson/the-power-of-a-simple-cache-system-with-javascript-map-3j01
  *
  * @param {Function} fn - the function whose result will be cached
  * @param {number} timeout - timeout in ms to clear the cache of a newly assigned value
+ * @param {number} maxSize - maximm number of elements in the cache
  * @returns {async Function} - a function that takes a value and caches its result.
  */
-const memoize = (fn, timeout = 2000) => {
+const memoize = (fn, timeout = 2000, maxSize = 200) => {
+  if (timeout <= 0 || maxSize <= 0) {
+    throw new Error("memoize: 'timeout' and 'maxSize' must be greater than 0.")
+  }
   const cache = new Map();
-  return async (n) => {
-    // stringify `n` to `key`, the key to find in the cache.
-    // since `map` is a key-value store, we need to stringify `n` to ensure it can be used as a key
-    // to ensure consistency, we sort our objects/array before stringifying
-    const key = JSON.stringify(recursiveSort(n));
+  return async (...args) => {
+    // if cache.size > cacheSize, remove the oldest items.
+    const extraCount = cache.size - maxSize;
+    if (extraCount > 0) {
+      // get the `extraCount` oldest items in the cache.
+      const deleteItems = [ ...cache.entries() ]  // convert iterator to array
+        .map(([ k, { timestamp }]) => [ k, timestamp ])
+        .sort((a, b) => a[1] - b[1])
+        .slice(0, extraCount);
+
+      deleteItems.forEach(([ k, _ ]) => cache.delete(k));
+    }
+
+    // stringify `args` to `key`, the key to find in the cache.
+    // since `map` is a key-value store, we need to stringify `args`
+    // to ensure it can be used as a key to ensure consistency,
+    // we sort our objects/array before stringifying
+    const key = JSON.stringify(recursiveSort(args));
+
+    // fetch result promise, from cache or by executing `fn`.
+    // instead of caching the result, we cache the promise:
+    // all concurrent callers awaiting the same key get the same promise
+    // instance, so `fn` is only ever called once per unique key,
+    // regardless of how many callers arrive before it resolves.
+    let promise;
     if (cache.has(key)) {
-      return cache.get(key);
+      promise = cache.get(key).promise;
     } else {
-      const result = await fn(n);  // apply the original arguments to `n`, not the sorted key.
-      cache.set(key, result);
+      promise = fn(...args);
+      cache.set(key, { timestamp: Date.now(), promise: promise });
       // after `timeout` ms, clear the cache of `key`
-      if (timeout > 0) {
-        setTimeout(
-          () => cache.delete(key),
-          timeout
-        )
-      }
-      return result;
+      setTimeout(
+        () => cache.delete(key),
+        timeout
+      )
     }
+
+    return await promise;
   }
 }