aiiinotate 0.4.3 → 0.5.0

package/README.md

@@ -105,7 +105,11 @@ Remember to have your `mongodb` service running: `sudo systemctl start mongod` !
 - **Start the app**
 
 ```bash
-npm run start
+# reload enabled
+npm run dev
+
+# reload disabled
+npm run prod
 ```
 
 - **Test the app**

package/docs/endpoints.md

@@ -12,7 +12,7 @@
     - your data must match the `iiif_version` argument
     - if you insert an Annotation following the API v3.x, you can't search for it using `iiif_version=2`.
 
-This is because 
+This is because
 - the IIIF standard is quite complex and there are breaking changes between v2 and v3
 - handling conversions between v2 and v3 is error prone, would increase calculations and slow the app down
 
@@ -32,20 +32,36 @@ Implementation of the [IIIF Search API](https://iiif.io/api/search/2.0/), to sea
 
 - Variables:
     - `iiif_version` (`2 | 3`): the IIIF aearch API version. 2 is for IIIF Presentation API 3.x, 1 is for IIIF Presentation API 2.x
-    - `manifest_short_id` (`string`): the ID of the manifest. See the *IIIF URIs* section. 
+    - `manifest_short_id` (`string`): the ID of the manifest. See the *IIIF URIs* section.
 - Parameters:
-    - `q` (`string`): query string. 
+    - `q` (`string`): query string.
         - if `iiif_version=1`, `q` is searched in the fields: `@id`, `resource.@id` or `resource.chars` fields
     - `motivation` (`painting | non-painting | commenting | describing | tagging | linking`): values for the `motivation` field of an annotation
+    - `canvasMin` (`number`): a positive integer
+    - `canvasMax` (`number`): a positive integer
+        - `canvasMax` must be greater than `canvasMin`
+        - if `canvasMax` is undefined, then we will only return the annotations that target a canvas at the `canvasMin` position in its manifest.
+    - `onlyIds` (`boolean`): return just the value of `@id` fields of matched annotations as a `string[]` instead of returning all the annotations,
 
 #### Response
 
-Returns a JSON. If `iiif_version` is `1`, an `AnnotationList` is returned. Otherwise, an `AnnotationPage` is returned.
+```
+AnnotationList | AnnotationPage | string[]
+```
+
+- if `onlyIds=true`, return a `string[]` (array of the IDs of all matched annotations)
+- otherwise,
+    - if `iiif_version` is `1`, return an `AnnotationList`
+    - else, return an `AnnotationPage`.
 
 #### Notes
 
-- if `q` and `motivation` are unused, it will return all annotations for the manifest
-- only exact matches are allowed for `q` and `motivation`
+- `canvasMin`, `canvasMax` and `onlyIds` are non-standard query parameters that are NOT part of the IIIF Search API specification.
+- If `q` and `motivation` are unused, it will return all annotations for the manifest
+- Only exact matches are allowed for `q` and `motivation`
+- About `canvasMin` and `canvasMax`:
+    - they are used to search for annotations that target a range of canvases: for example, fetch all anotations between pages 3 and 30 of a manuscript.
+    - See section **Create/update an annotation** for more information and possible issues with canvas indexes.
 
 ---
 
@@ -75,7 +91,7 @@ DELETE /{collection_name}/{iiif_version}/delete
 { deletedCount: <integer> }
 ```
 
---- 
+---
 
 ## Manifests routes
 
@@ -106,14 +122,14 @@ POST /manifests/{iiif_version}/create
 
 #### Request
 
-- Variable: 
+- Variable:
     - `iiif_version` (`2 | 3`): the IIIF Presentation API version of your manifest
 - Body (`JSON`): the manifest  to index in the database
 
 #### Response
 
 ```
-{ 
+{
     insertedIds: string[],
     preExistingIds: string[],
     rejectedIds: []
@@ -205,15 +221,18 @@ Create or update a single annotation
 - Variables:
     - `iiif_version` (`2 | 3`): the IIIF version of the annotation
     - `action` (`create | update`): the action to perform: create or update an annotation
+- Parameters:
+    - `throwOnCanvasIndexError` (`boolean`): if there is an error fetching the related manifest, or getting a target canvas' index, throw an error.
 - Body (`Object`): a IIIF annotation that follows the IIIF Presentation API 2 or 3 (depending on the value of `iiif_version`)
 
 #### Response
 
 ```
-{ 
+{
     insertedIds: string[],
     preExistingIds: string[],
-    rejectedIds: []
+    rejectedIds: string[],
+    fetchErrorIds: string[]
 }
 ```
 
@@ -227,7 +246,10 @@ Create or update a single annotation
     - `annotation.on[0].canvasIdx`: the position of an annotation's target canvas within the target manifest, as an integer
     - this depends on reconstructing an annotation's target manifest URL and fetching it. If this process fails, the fields above will be `undefined`.
     - the annotation's target's manifest is fetched and inserted in the database, if possible, and stored in `annotation.on[0].manifestShortId`
-
+- If `throwOnCanvasIndexError`, an error will be thrown if an error appears anywhere in the proicess of fetching the target manifest or populating the `canvasIdx` field.
+    - fetching an annotation's target manfest is error prone: it depends on the manifest being available through HTTP, which is not in our control.
+    - in turn, normally, if there's an error, we will just add the issue to `fetchErrorIds` and not throw.
+    - in controlled environments where you know your manifests WILL be available and where you rely heavily on the `canvasIdx` field (like AIKON), throwing an error will ensure that the `canvasIdx` field is always defined.
 
 ---
 
@@ -241,7 +263,7 @@ Batch insert multiple annotations.
 
 #### Request
 
-- Parameters: 
+- Parameters:
     - `iiif_version` (`2 | 3`): the IIIF version of the annotation
 - Body: either:
     - a full `AnnotationList | AnnotationPage` embedded in the body (type must match `iiif_version`: AnnotationPage for IIIF 3, AnnotationList for IIIF 2).
@@ -252,7 +274,7 @@ Batch insert multiple annotations.
 #### Response
 
 ```
-{ 
+{
     insertedIds: string[],
     preExistingIds: string[],
     rejectedIds: []

package/docs/todo.md

@@ -0,0 +1,19 @@
+# TODO
+
+## Short term
+
+- **pagination**
+    - add pagination to responses (`next` field in AnnotationLists)
+    - add `pageNumber` and `limit` parameters to routes to be able to specify page numbers and number of items in page from GET queries
+- **update Mongo indexes** 
+    - to reflect database changes (`annotation.on` is now an array)
+    - on frequently queried fields (`annotation.on.canvasIdx`, `annotation.on.manifestShortId`... => see what else is used in GET routes)
+- **sort annotations collections**
+    - by `canvasIdx` 
+    - by position on the page (y-offset then x-offset, see `xywh`)
+
+
+## Mid term
+
+- **aiiinotate CLI** to import and export data easily
+- **IIIF presentation 3**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiiinotate",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "a fast IIIF-compliant annotation server",
   "main": "./cli/index.js",
   "type": "module",
@@ -13,8 +13,9 @@
   "scripts": {
     "cli": "node ./cli/index.js --env=./config/.env",
     "setup": "sudo systemctl start mongod && npm run cli migrate apply",
-    "start": "sudo systemctl start mongod && npm run cli serve dev",
-    "test": "sudo systemctl start mongod && dotenvx run -f ./config/.env -- node --test --test-isolation=none",
+    "dev": "sudo systemctl start mongod && nodemon --watch ./src --exec \"npm run cli serve dev\"",
+    "prod": "sudo systemctl start mongod && npm run cli serve prod",
+    "test": "export AIIINOTATE_TESTING=true; sudo systemctl start mongod && dotenvx run -f ./config/.env -- node --test --test-isolation=none",
     "lint": "npx eslint --fix",
     "migrate": "npm run cli -- migrate",
     "update_version": "python3 scripts/update_version.py"
@@ -47,7 +48,7 @@
     "#schemas/*.js": "./src/schemas/*.js",
     "#config/*.js": "./config/*.js",
     "#data/*.js": "./src/data/*.js",
-    "#utils/*.js": "./src/data/utils/*.js",
+    "#utils/*.js": "./src/utils/*.js",
     "#fixtures/*.js": "./src/fixtures/*.js",
     "#fixtures/*.json": "./src/fixtures/*.json",
     "#manifests/*.js": "./src/data/manifests/*.js",
@@ -70,9 +71,10 @@
     "@eslint/css": "^0.10.0",
     "@eslint/js": "^9.33.0",
     "@eslint/json": "^0.13.1",
+    "@fastify/pre-commit": "^2.2.1",
     "@stylistic/eslint-plugin": "^5.2.3",
     "eslint": "^9.33.0",
     "globals": "^16.3.0",
-    "pre-commit": "^1.2.2"
+    "nodemon": "^3.1.11"
   }
-}
+}

package/src/data/annotations/annotations2.js

@@ -191,11 +191,12 @@ class Annotations2 extends CollectionAbstract {
    * - 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) {
-    // TODO  : extract all canvas Ids, reconstruct manifest IDs from it. if they're valid, insert the manifests into the db.
+  async #insertManifestsAndGetCanvasIdx(annotationData, throwOnCanvasIndexError=false) {
+    // 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
+    let converted;
     [ annotationData, converted ] = maybeToArray(annotationData, true);
 
     // 1. get all distinct manifest URIs
@@ -209,22 +210,28 @@ class Annotations2 extends CollectionAbstract {
     // 2. insert the manifests
     // NOTE: PERFORMANCE significantly drops because of this: test running for the entire app goes from ~1000ms to ~2600ms
     const
-      insertResponse = await this.manifestsPlugin.insertManifestsFromUriArray(manifestUris, false),
+      insertResponse = await this.manifestsPlugin.insertManifestsFromUriArray(manifestUris, throwOnCanvasIndexError),
       /** @type {string[]} concatenation of ids of newly inserted manifests and previously inserted manifests. */
       insertedManifestsIds = insertResponse.insertedIds.concat(insertResponse.preExistingIds || []);
 
-    // 3. update annotations with 2 things:
-    //  - where manifest insertion has failed, set `manifestUri` to undefined on all values of `annotation.on`
-    //  - set `annotation.on.canvasIdx`: the position of the target canvas within the manifest, or undefined if it cound not be found.
+    if ( throwOnCanvasIndexError && insertResponse.fetchErrorIds.length ) {
+      visibleLog("THIS SHOULD NOT HAPPEN")
+    }
+
+    // 3. update annotations with info on manifest and canvas.
+    // if canvasIdx is undefined, throw.
     annotationData = await Promise.all(
       annotationData.map(async (ann) => {
         ann.on = await Promise.all(
           ann.on.map(async (target) => {
+            //  a. where manifest insertion has failed, set `manifestUri` to undefined on all values of `annotation.on`
             target.manifestUri =
               // has the insertion of `manifestUri` worked ? (has it returned a valid response, woth `insertedIds` key).
               insertedManifestsIds.find((x) => x === target.manifestUri)
                 ? target.manifestUri
                 : undefined;
+
+            // b. set `annotation.on.canvasIdx`: the position of the target canvas within the manifest, or undefined if it cound not be found.
             target.canvasIdx =
               target.manifestUri
                 ? await this.manifestsPlugin.getCanvasIdx(target.manifestUri, target.full)
@@ -232,6 +239,9 @@ class Annotations2 extends CollectionAbstract {
             return target;
           })
         )
+        if ( throwOnCanvasIndexError &&  ann.on.some((target) => target.canvasIdx === undefined) ) {
+          throw new this.insertError(`${this.funcName(this.deleteAnnotations)}: could not get canvasIdx for annotation`);
+        }
         return ann;
       })
     );
@@ -247,12 +257,18 @@ class Annotations2 extends CollectionAbstract {
 
   /**
    * validate and insert a single annotation.
-   * @param {object} annotationArray
+   *
+   * 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.
+   *
+   * @param {object} annotation
+   * @param {boolean?} throwOnCanvasIndexError
    * @returns {Promise<InsertResponseType>}
    */
-  async insertAnnotation(annotation) {
+  async insertAnnotation(annotation, throwOnCanvasIndexError=false) {
     annotation = this.#cleanAnnotation(annotation);
-    annotation = await this.#insertManifestsAndGetCanvasIdx(annotation);
+    annotation = await this.#insertManifestsAndGetCanvasIdx(annotation, throwOnCanvasIndexError);
     return this.insertOne(annotation);
   }
 
@@ -273,13 +289,19 @@ class Annotations2 extends CollectionAbstract {
 
   /**
    * 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.
+   *
    * @param {object} annotationList
+   * @param {boolean?} throwOnCanvasIndexError
    * @returns {Promise<InsertResponseType>}
    */
-  async insertAnnotationList(annotationList) {
+  async insertAnnotationList(annotationList, throwOnCanvasIndexError) {
     let annotationArray;
     annotationArray = this.#cleanAnnotationList(annotationList);
-    annotationArray = await this.#insertManifestsAndGetCanvasIdx(annotationArray);
+    annotationArray = await this.#insertManifestsAndGetCanvasIdx(annotationArray, throwOnCanvasIndexError);
     return this.insertMany(annotationArray);
   }
 
@@ -349,27 +371,47 @@ class Annotations2 extends CollectionAbstract {
    * 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` and `canvasMax` parameters are implemented: search by annotation's target canvas position.
+   * - 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 {string} queryUrl
-   * @param {string} manifestShortId
-   * @param {string?} q
-   * @param {"painting"|"non-painting"|"commenting"|"describing"|"tagging"|"linking"?} motivation
-   * @param {number?} canvasMin - minimum value of `on.canvasIdx`, inclusive
-   * @param {number?} canvasMax - maximum value of `on.canvasIdx`, inclusive
+   * @param {{
+   *   queryUrl: string,
+   *   manifestShortId: string,
+   *   q: string?,
+   *   motivation: ("painting"|"non-painting"|"commenting"|"describing"|"tagging"|"linking")?,
+   *   canvasMin: number?,
+   *   canvasMax: number?,
+   *   onlyIds: boolean
+   * }}
    * @returns {object} annotationList containing results
    */
-  async search(queryUrl, manifestShortId, q, motivation, canvasMin, canvasMax) {
+  async search({
+    queryUrl,
+    manifestShortId,
+    q,
+    motivation=undefined,
+    canvasMin=undefined,
+    canvasMax=undefined,
+    onlyIds=false
+  }) {
     const
       queryBase = { "on.manifestShortId": manifestShortId },
       queryFilters = { $and: [] };
@@ -393,20 +435,17 @@ class Annotations2 extends CollectionAbstract {
             : { motivation: `oa:${motivation}` }
       );
     };
-    // TODO test
-    if ( canvasMin ) {
+    if ( !isNaN(canvasMin) ) {
       // if canvasMax is undefined, then search for canvasIdx===canvasMin
       if ( !canvasMax ) {
         queryFilters.$and.push({ "on.canvasIdx": canvasMin })
       // if canvasMin and canvasMax, canvasIdx must be in [canvasMin, canvasMax] (inclusive).
       } else {
         queryFilters.$and.push({
-          "on.canvasIdx": {
-            $and: [
-              { $gte: canvasMin },
-              { $lte: canvasMax },
-            ]
-          }
+          $and: [
+            { "on.canvasIdx": { $gte: canvasMin } },
+            { "on.canvasIdx": { $lte: canvasMax } }
+          ]
         })
       }
     }
@@ -415,8 +454,13 @@ class Annotations2 extends CollectionAbstract {
         ? { ...queryBase, ...queryFilters }
         : queryBase;
 
-    const annotations = await this.find(query);
-    return toAnnotationList(annotations, queryUrl, `search results for query ${queryUrl}`);
+    if ( !onlyIds ) {
+      const annotations = await this.find(query);
+      return toAnnotationList(annotations, queryUrl, `search results for query ${queryUrl}`);
+    } else {
+      return ( await this.find(query, { "@id": 1 }) )
+        .map((ann) => ann["@id"]);
+    }
   }
 
   /**

package/src/data/annotations/routes.js

@@ -176,7 +176,7 @@ function annotationsRoutes(fastify, options, done) {
     async (request, reply) => {
       const
         annotationUri = pathToUrl(request.url),
-        { iiifPresentationVersion} = request.params;
+        { iiifPresentationVersion } = request.params;
       try {
         return iiifPresentationVersion === 2
           ? annotations2.findById(annotationUri)
@@ -202,6 +202,22 @@ function annotationsRoutes(fastify, options, done) {
             action: { type: "string", enum: [ "create", "update" ] }
           }
         },
+        // NOTE: throwOnCanvasIndexError is only implemented if `action==="create"` (see preValidation)
+        querystring: {
+          type: "object",
+          properties: {
+            throwOnCanvasIndexError: { type: "boolean" },
+          }
+        },
+        preValidation: async (request, reply) => {
+          const
+            { action } = request.params,
+            { throwOnCanvasIndexError } = request.querystring;
+          if ( action==="update" && throwOnCanvasIndexError ) {
+            returnError(request, reply, "'throwOnCanvasIndexError' is only allowed when ':action' is 'create'.")
+          }
+          return;
+        },
         body: routeAnnotation2Or3Schema,
         response: responsePostSchema
       },
@@ -209,6 +225,7 @@ function annotationsRoutes(fastify, options, done) {
     async (request, reply) => {
       const
         { iiifPresentationVersion, action } = request.params,
+        { throwOnCanvasIndexError } = request.query,
         annotation = request.body;
 
       try {
@@ -216,7 +233,7 @@ function annotationsRoutes(fastify, options, done) {
         // insert or update
         if ( iiifPresentationVersion === 2 ) {
           return action==="create"
-            ? await annotations2.insertAnnotation(annotation)
+            ? await annotations2.insertAnnotation(annotation, throwOnCanvasIndexError)
             : await annotations2.updateAnnotation(annotation);
         } else {
           annotations3.notImplementedError();
@@ -251,6 +268,12 @@ function annotationsRoutes(fastify, options, done) {
             iiifPresentationVersion: iiifPresentationVersionSchema
           }
         },
+        querystring: {
+          type: "object",
+          properties: {
+            throwOnCanvasIndexError: { type: "boolean", },
+          }
+        },
         body: routeAnnotationCreateManySchema,
         response: responsePostSchema
       }
@@ -258,6 +281,7 @@ function annotationsRoutes(fastify, options, done) {
     async (request, reply) => {
       const
         { iiifPresentationVersion } = request.params,
+        { throwOnCanvasIndexError } = request.query,
         body = maybeToArray(request.body),  // convert to an array to have a homogeneous data structure
         insertResponseArray = [];
 
@@ -282,7 +306,7 @@ function annotationsRoutes(fastify, options, done) {
         if ( iiifPresentationVersion === 2 ) {
           await Promise.all(annotationsArray.map(
             async (annotationList) => {
-              const r = await annotations2.insertAnnotationList(annotationList);
+              const r = await annotations2.insertAnnotationList(annotationList, throwOnCanvasIndexError);
               insertResponseArray.push(r);
             }
           ));

package/src/data/annotations/routes.test.js

@@ -55,8 +55,9 @@ test("test annotation Routes", async (t) => {
       return a;
     });
 
+    // test basic inserts
     //NOTE: we can't do Promise.all because it causes a data race that can cause a failure of unique constraints (i.e., on manifests '@id')
-    const data = [
+    let data = [
       [[ annotationListUri, annotationListUriArray, annotationList, annotationListArrayLimit ], testPostRouteCreateSuccess],
       [[ annotationListUriInvalid, annotationListUriArrayInvalid ], testPostRouteCreateFailure]
     ];
@@ -66,11 +67,29 @@ test("test annotation Routes", async (t) => {
         await func(t, "/annotations/2/createMany", testData.at(i));
       }
     }
+
+    // test that `throwOnCanvasIndexError` throws errors when it's supposed to
+    const annotationListWithTargetErrors = structuredClone(annotationList);
+    // replace the annotation.on with an uuid => should trigger an error.https://www.cinefil.com/film/mulholland-drive
+    annotationListWithTargetErrors.resources =
+      annotationListWithTargetErrors
+        .resources
+        .map((annotation) => {
+          // if annotation.on is a string, the annotation should have a fragment
+          annotation.on = `https://test/${uuid4()}#xywh=100,100,300,300`;
+          return annotation
+        });
+
+    data = [[testPostRouteCreateFailure, true], [testPostRouteCreateSuccess, false]];
+    for (let i=0; i<data.length; i++) {
+      const [func, v] = data.at(i);
+      func(t, `/annotations/2/createMany?throwOnCanvasIndexError=${v}`, annotationListWithTargetErrors)
+    }
   })
 
   await t.test("test route /annotations/:iiifPresentationVersion/create", async (t) => {
     //NOTE: we can't do Promise.all because it causes a data race that can cause a failure of unique constraints (i.e., on manifests '@id')
-    const data = [
+    let data = [
       [fastify.fixtures.annotations2Valid, testPostRouteCreateSuccess],
       [fastify.fixtures.annotations2Invalid, testPostRouteCreateFailure],
     ]
@@ -80,6 +99,15 @@ test("test annotation Routes", async (t) => {
         await func(t, "/annotations/2/create", testData.at(i));
       }
     };
+
+    // test throwOnCanvasIndexError
+    const annotationWithTargetError = structuredClone(fastify.fixtures.annotations2Valid.at(0));
+    annotationWithTargetError.on = `https://test/${uuid4()}#xywh=100,100,300,300`;
+    data = [[testPostRouteCreateFailure, true], [testPostRouteCreateSuccess, false]];
+    for (let i=0; i<data.length; i++) {
+      const [func, v] = data.at(i);
+      await func(t, `/annotations/2/create?throwOnCanvasIndexError=${v}`, annotationWithTargetError)
+    }
   })
 
   await t.test("test route /annotations/:iiifPresentationVersion/update", async (t) => {

package/src/data/collectionAbstract.js

@@ -1,5 +1,5 @@
 import { maybeToArray, inspectObj } from "#utils/utils.js"
-import { formatInsertResponse, formatDeleteResponse, formatUpdateResponse } from "#src/data/utils/routeUtils.js";
+import { formatInsertResponse, formatDeleteResponse, formatUpdateResponse } from "#utils/routeUtils.js";
 
 /** @typedef {import("#types").MongoDbType} MongoDbType */
 /** @typedef {import("#types").MongoClientType} MongoClientType */
@@ -94,7 +94,7 @@ class CollectionAbstract {
     this.errorConstructor = errorConstructor(collectionName);
     /** @type {Function(string, object?) => Error} */
     this.errorNoAction = this.errorConstructor(undefined);
-    // create this.error(Read|Insert|Update|Delete), properties that will be used to throw the proper error.
+    // create this.(read|insert|update|delete)Error, properties that will be used to throw the proper error.
     [ "read", "insert", "update", "delete" ].forEach((op) =>
       /** @type {Function(string,object?) => Error} */
       this[`${op}Error`] = errorConstructor(collectionName)(op)
@@ -148,7 +148,7 @@ class CollectionAbstract {
       // MongoInsertOneResultType and MongoInsertManyResultType have a different structureex
       mongoRes.insertedId || Object.values(mongoRes.insertedIds)
     );
-    return formatInsertResponse(insertedIds);
+    return formatInsertResponse({ insertedIds });
   }
 
   /**