aiiinotate 0.5.1 → 0.6.0

package/config/.env.template

@@ -14,6 +14,9 @@ AIIINOTATE_HOST=127.0.0.1
 # HTTP scheme: HTTP or HTTPS. should be HTTP in dev and in docker
 AIIINOTATE_SCHEME=http
 
+# max number of items to display per result page
+PAGE_SIZE=5000
+
 # IGNORE
 AIIINOTATE_BASE_URL="$AIIINOTATE_SCHEME://$AIIINOTATE_HOST:$AIIINOTATE_PORT"
 # IGNORE

package/docs/endpoints.md

@@ -2,6 +2,15 @@
 
 ## Introductory notes
 
+### Terminology
+
+In the docs below,
+
+- `Parameters` describes route parameters (dynamic segments of a route's URL).
+- `Query` describes the query string in a key-value format
+
+### IIIF Version
+
 **aiiinotate** is meant to be able to handle both IIIF presentation APIs: the most common [2.x](https://iiif.io/api/presentation/2.1) and the more recent [3.x](https://iiif.io/api/presentation/3.0). Both APIs define a data structure for manifests, annotations, lists of annotations and collections of manifests.
 
 **HOWEVER, in aiiinotate, IIIF Presentation v2 and v3 data are isolated**: they form two separate collections, and no conversion is done between IIIF 2.x and 3.x data. This means that:
@@ -30,10 +39,10 @@ Implementation of the [IIIF Search API](https://iiif.io/api/search/2.0/), to sea
 
 #### Request
 
-- Variables:
+- Parameters:
     - `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.
-- Parameters:
+- Query:
     - `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
@@ -41,7 +50,9 @@ Implementation of the [IIIF Search API](https://iiif.io/api/search/2.0/), to sea
     - `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,
+    - `page` (`number`): results are paginated. This specifies the page number
+    - `pageSize` (`number`): number of annotations to display per page. Defaults to `process.env.PAGE_SIZE`.
+    - `onlyIds` (`boolean`): return just the value of `@id` fields of matched annotations as a `string[]` instead of returning all the annotations. If `onlyIds=true`, there is no pagination, `page` and `pageSize` won't have any effect.
 
 #### Response
 
@@ -73,10 +84,10 @@ DELETE /{collection_name}/{iiif_version}/delete
 
 #### Request
 
-- Variables
+- Parameters:
     - `collection_name` (`annotations | manifests`): delete an annotation or a manifest
     - `iiif_version` (`2 | 3`): IIIF presentation version
-- Parameters:
+- Query:
     - if `collection_name = manifests`:
         - `uri`: the full URI of the manifest to delete
         - `manifestShortId`: the manifest's identifier
@@ -105,7 +116,7 @@ Returns a Collection of all manifests in your **aiiinotate** instance.
 
 #### Request
 
-- Variables:
+- Parameters:
     - `iiif_version` (`2 | 3`): the IIIF Presentation API version
 
 #### Response
@@ -122,7 +133,7 @@ POST /manifests/{iiif_version}/create
 
 #### Request
 
-- Variable:
+- Parameters:
     - `iiif_version` (`2 | 3`): the IIIF Presentation API version of your manifest
 - Body (`JSON`): the manifest  to index in the database
 
@@ -152,15 +163,20 @@ GET /annotations/{iiif_version}/search
 
 #### Request
 
-- Variables:
-    - `iiif_version` (`2 | 3`): the IIIF Presentation API of your manifests
 - Parameters:
-    - `uri` (`string`): the URI of the target canvas
-    - `asAnnotationList` (`true | false`):  format of the response
+    - `iiif_version` (`2 | 3`): the IIIF Presentation API of your manifests
+- Query:
+    - `canvasUri` (`string`): the URI of the target canvas
+    - `page` (`number`): results are paginated. Specifies the page number.
+    - `pageSize` (`number`): number of items per page. Defaults to `process.env.PAGE_SIZE`.
 
 #### Response
 
-`Object[] | Object`: if `true`, return an array of annotations. Otherwise, return an `AnnotationList`.
+Results are paginated.
+
+```
+AnnotationList | AnnotationPage
+``` 
 
 ---
 
@@ -172,9 +188,9 @@ GET /annotations/{iiif_version}/count
 
 #### Request
 
-- Variables:
-    - `iiif_version` (`2 | 3`): the IIIF Presentation API of your manifests
 - Parameters:
+    - `iiif_version` (`2 | 3`): the IIIF Presentation API of your manifests
+- Query:
     - `uri` (`string`): the annotation's `@id`
     - `canvasUri` (`string`): the annotation's target canvas (`on.full`)
     - `manifestShortId` (`string`): the short ID of the annotation's target manifest (`on.manifestShortId`)
@@ -197,7 +213,7 @@ This route allows to query an annotation by its ID by defering its `@id | id` fi
 
 #### Request
 
-- Variables:
+- Parameters:
     - `iiif_version` (`2 | 3`): the IIIF version of the annotation
     - `manifest_short_id` (`string`): the identifier of the manifest the annotation is related to
     - `annotation_short_id`: the unique part of the annotation URL
@@ -218,10 +234,10 @@ Create or update a single annotation
 
 #### Request
 
-- Variables:
+- Parameters:
     - `iiif_version` (`2 | 3`): the IIIF version of the annotation
     - `action` (`create | update`): the action to perform: create or update an annotation
-- Parameters:
+- Query:
     - `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`)
 
@@ -263,7 +279,7 @@ Batch insert multiple annotations.
 
 #### Request
 
-- Parameters:
+- Query:
     - `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).

package/docs/specifications/2_iiif_apis.md

@@ -394,3 +394,35 @@ Properties of the annotation list are:
 }
 ```
 
+### Pagination
+
+A paginated resource can be for example a  `Collection` or an `AnnotationList`. 
+
+- A paginated Resource (i.e., a `Collection`)
+    - MUST use `first` to link to the first page
+    - MUST NOT embed the corresponding list that is being pagiated
+- A page (i.e., a single page of an `AnnotationList`)
+    - SHOULD use `within` to refer to its container resource
+    - MUST use `next` to provide a link to the next page, if it exists
+    - SHOULD use `prev` to provide a link to the previous page, if it exists
+    - MAY use `total` to list the total number of resources contained in all pages
+    - MAY use `startIndex` to document the index of the first item of the current page, starting from 0 (i.e., if you're on page 3 and there are 100 annotations per page, `startIndex: 300`)
+    - MAY inherit descriptive properties from the paged resource (i.e. the `logo` or `attribution`).
+
+```js
+// the first page of an annotation list
+{
+  "@context": "http://iiif.io/api/presentation/2/context.json",
+  "@id": "http://example.org/iiif/book1/list/l1",
+  "@type": "sc:AnnotationList",
+
+  "startIndex": 0,
+  "within": "http://example.org/iiif/book1/layer/transcription",
+  "next": "http://example.org/iiif/book1/list/l2",
+
+  "resources": [
+    // Annotations live here ...
+  ]
+}
+```
+

package/migrations/migrationScripts/20250825185706-collections.js

@@ -6,6 +6,8 @@
  * - manifests2   : IIIF manifests following the IIIF 2.1 (and 2.0) presentation API
  */
 
+import { inspectObj } from "#utils/utils.js";
+
 const collectionNames = [
   "annotations3",
   "annotations2",
@@ -19,10 +21,16 @@ const collectionNames = [
  * @returns {Promise<void>}
  */
 export const up = async (db, client) => {
-  // See https://github.com/seppevs/migrate-mongo/#creating-a-new-migration-script
-  collectionNames.forEach((colName) => {
-    db.createCollection(colName);
-  })
+  // check if a collection exists before recreating it, otherwise you get NameSpaceExists errors.
+  const existingCollectionNames =
+    ( await db.listCollections().toArray() ).map(coll => coll.name);
+
+  // create a mongo collection: https://github.com/seppevs/migrate-mongo/#creating-a-new-migration-script
+  for (const colName of collectionNames ) {
+    if ( !existingCollectionNames.includes(colName) ) {
+      db.createCollection(colName);
+    }
+  }
 };
 
 /**
@@ -31,11 +39,10 @@ export const up = async (db, client) => {
  * @returns {Promise<void>}
  */
 export const down = async (db, client) => {
-  // Example:
-  // await db.collection('albums').updateOne({artist: 'The Beatles'}, {$set: {blacklisted: false}});
-  collectionNames.forEach(async (colName) => {
-    const collection = db.collection(colName);
-    await collection.drop();
-  })
+  // NOTE : here, `down` does NOT revert the migration: it would delete the collections and their contents, which we don't want. it's ok since this is the first migration.
+  // collectionNames.forEach(async (colName) => {
+  //   const collection = db.collection(colName);
+  //   await collection.drop();
+  // })
 }
 

package/migrations/migrationScripts/20250904080710-annotations2-indexes.js

@@ -0,0 +1,69 @@
+/**
+ * create and manage indexes for the collection `annotations2`
+ */
+
+import {createIndex, removeIndex} from "../manageIndex.js";
+
+
+// all filters on arrays are MultiKey index => it NOT a Sort index, but an Equality index (useful for filters)
+const indexes = [
+  {
+    colName: "annotations2",
+    indexSpec: { "@id": 1 },
+    indexOptions: { name: "annotationIdIndex" }
+  },
+  {
+    colName: "annotations2",
+    indexSpec: { "on.full": 1 },
+    indexOptions: { name: "canvasIdIndex" }
+  },
+  {
+    colName: "annotations2",
+    indexSpec: { "on.manifestUri": 1 },
+    indexOptions: { name: "manifestIdIndex" }
+  },
+  {
+    colName: "annotations2",
+    indexSpec: { "on.manifestShortId": 1 },
+    indexOptions: { name: "manifestShortIdIndex" }
+  },
+  {
+    colName: "annotations2",
+    indexSpec: { "on.canvasIdx": 1 },
+    indexOptions: { name: "canvasIdxIndex" }
+  },
+  {
+    colName: "annotations2",
+    indexSpec: { "on.resource.@id": 1 },
+    indexOptions: { name: "resourceIdIndex" }
+  },
+  {
+    colName: "annotations2",
+    indexSpec: { "on.resource.chars": 1 },
+    indexOptions: { name: "resourceCharsIndex" }
+  }
+]
+
+/**
+ * @param {import('mongodb').Db} db
+ * @param {import('mongodb').MongoClient} client
+ * @returns {Promise<void>}
+ */
+export const up = async (db, client) => {
+  for ( const { colName, indexSpec, indexOptions } of indexes ) {
+    const result = await createIndex(db, colName, indexSpec, indexOptions);
+    console.log("created index:", result);
+  }
+};
+
+/**
+ * @param {import('mongodb').Db} db
+ * @param {import('mongodb').MongoClient} client
+ * @returns {Promise<void>}
+ */
+export const down = async (db, client) => {
+  for ( const { colName, indexSpec, indexOptions } of indexes ) {
+    const result = await removeIndex(db, colName, indexOptions);
+    console.log("dropped index:", result);
+  }
+};

package/migrations/migrationScripts/20251006212110-manifests2-indexes.js

@@ -0,0 +1,35 @@
+/** create indexes for manifests2 collection */
+
+import {createIndex, removeIndex} from "../manageIndex.js";
+
+const indexes = [
+  {
+    colName: "manifests2",
+    indexSpec: { "@id": 1 },
+    indexOptions: { name: "manifestIdIndex", unique: true }
+  },
+]
+
+/**
+ * @param {import('mongodb').Db} db
+ * @param {import('mongodb').MongoClient} client
+ * @returns {Promise<void>}
+ */
+export const up = async (db, client) => {
+  for ( const { colName, indexSpec, indexOptions } of indexes ) {
+    const result = await createIndex(db, colName, indexSpec, indexOptions);
+    console.log("created index:", result);
+  }
+};
+
+/**
+ * @param {import('mongodb').Db} db
+ * @param {import('mongodb').MongoClient} client
+ * @returns {Promise<void>}
+ */
+export const down = async (db, client) => {
+  for ( const { colName, indexSpec, indexOptions } of indexes ) {
+    const result = await removeIndex(db, colName, indexOptions);
+    console.log("dropped index:", result);
+  }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiiinotate",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "a fast IIIF-compliant annotation server",
   "main": "./cli/index.js",
   "type": "module",
@@ -18,7 +18,8 @@
     "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"
+    "update_version": "python3 scripts/update_version.py",
+    "get_version": "python3 scripts/get_version.py"
   },
   "pre-commit": [
     "lint"
@@ -61,9 +62,11 @@
     "@fastify/mongodb": "^9.0.2",
     "@fastify/swagger": "^9.5.2",
     "commander": "^14.0.0",
+    "fast-xml-parser": "^5.3.3",
     "fastify": "^5.5.0",
     "migrate-mongo": "^12.1.3",
     "mongodb": "^6.18.0",
+    "svg-path-bbox": "^2.1.0",
     "swagger-markdown": "^3.0.0",
     "uuid": "^11.1.0"
   },

package/src/data/annotations/annotations2.js

@@ -6,10 +6,11 @@ import fastifyPlugin from "fastify-plugin";
 
 import CollectionAbstract from "#data/collectionAbstract.js";
 import { IIIF_PRESENTATION_2_CONTEXT } from "#utils/iiifUtils.js";
-import { ajvCompile, objectHasKey, isNullish, maybeToArray, inspectObj, visibleLog } from "#utils/utils.js";
+import { ajvCompile, objectHasKey, isNullish, maybeToArray, inspectObj, visibleLog, memoize } from "#utils/utils.js";
 import { getManifestShortId, makeTarget, makeAnnotationId, toAnnotationList, canvasUriToManifestUri } from "#utils/iiif2Utils.js";
 
 
+/** @typedef {import("mongodb").FindCursor} FindCursor */
 /** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
 /** @typedef {import("#types").MongoObjectId} MongoObjectId */
 /** @typedef {import("#types").MongoInsertResultType} MongoInsertResultType */
@@ -58,6 +59,15 @@ class Annotations2 extends CollectionAbstract {
   ////////////////////////////////////////////////////////////////
   // utils
 
+
+  /**
+   * @type {() => 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
@@ -93,7 +103,6 @@ class Annotations2 extends CollectionAbstract {
 
       // 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
-      // delete the alternate keys
       [ "value", "cnt:chars" ].map((k) => {
         if ( Object.keys(resource).includes(k) ) {
           delete resource[k];
@@ -123,11 +132,11 @@ class Annotations2 extends CollectionAbstract {
    * @param {boolean} update - set to `true` if performing an update instead of an insert.
    * @returns {object}
    */
-  #cleanAnnotation(annotation, update=false) {
+  async #cleanAnnotation(annotation, update=false) {
     // 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 = makeTarget(annotation),
-      // we assume that all values of `annotationTargetArray` point to the same manifest => take the manifest of the 1st target
+      annotationTargetArray = await makeTarget(annotation),
       manifestShortId = annotationTargetArray[0].manifestShortId;
 
     // in updates, "@id" has aldready been extracted
@@ -176,13 +185,17 @@ class Annotations2 extends CollectionAbstract {
    * @param {object} annotationList
    * @returns {object[]}
    */
-  #cleanAnnotationList(annotationList) {
+  async #cleanAnnotationList(annotationList) {
     // 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)
     }
     //NOTE: using an arrow function is necessary to avoid losing the scope of `this`. otherwise, `this` is undefined in `#cleanAnnotation`.
-    return annotationList.resources.map((ressource) => this.#cleanAnnotation(ressource))
+    return await Promise.all(
+      annotationList.resources.map(async (ressource) =>
+        await this.#cleanAnnotation(ressource)
+      )
+    )
   }
 
   /**
@@ -214,10 +227,6 @@ class Annotations2 extends CollectionAbstract {
       /** @type {string[]} concatenation of ids of newly inserted manifests and previously inserted manifests. */
       insertedManifestsIds = insertResponse.insertedIds.concat(insertResponse.preExistingIds || []);
 
-    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(
@@ -252,6 +261,57 @@ class Annotations2 extends CollectionAbstract {
       : 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.
+   *
+   * 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 {object} - paginated annotation list
+   */
+  async #paginate({
+    queryUrl,
+    queryFilter,
+    page=1,
+    pageSize=process.env.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
 
@@ -267,7 +327,7 @@ class Annotations2 extends CollectionAbstract {
    * @returns {Promise<InsertResponseType>}
    */
   async insertAnnotation(annotation, throwOnCanvasIndexError=false) {
-    annotation = this.#cleanAnnotation(annotation);
+    annotation = await this.#cleanAnnotation(annotation);
     annotation = await this.#insertManifestsAndGetCanvasIdx(annotation, throwOnCanvasIndexError);
     return this.insertOne(annotation);
   }
@@ -280,7 +340,7 @@ class Annotations2 extends CollectionAbstract {
    */
   async updateAnnotation(annotation) {
     // necessary: on insert, the `@id` received is modified by `this.#cleanAnnotationList`.
-    annotation = this.#cleanAnnotation(annotation, true);
+    annotation = await this.#cleanAnnotation(annotation, true);
     const
       query = { "@id": annotation["@id"] },
       update = { $set: annotation };
@@ -300,7 +360,7 @@ class Annotations2 extends CollectionAbstract {
    */
   async insertAnnotationList(annotationList, throwOnCanvasIndexError) {
     let annotationArray;
-    annotationArray = this.#cleanAnnotationList(annotationList);
+    annotationArray = await this.#cleanAnnotationList(annotationList);
     annotationArray = await this.#insertManifestsAndGetCanvasIdx(annotationArray, throwOnCanvasIndexError);
     return this.insertMany(annotationArray);
   }
@@ -331,11 +391,12 @@ class Annotations2 extends CollectionAbstract {
    * 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
+   * @param {object} queryObj - the filter document
    * @param {object?} projectionObj - extra projection fields to tailor the reponse format
-   * @returns {Promise<object[]>}
+   * @param {boolean} asCursor - return a cursor instead of an array of results
+   * @returns {Promise<object[] | FindCursor>}
    */
-  async find(queryObj, projectionObj={}) {
+  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 =
@@ -362,9 +423,12 @@ class Annotations2 extends CollectionAbstract {
     }
 
     // 2. find, project and return
-    return this.collection
-      .find(queryObj, { projection: projectionObj })
-      .toArray();
+    const cursor = this.collection.find(queryObj, { projection: projectionObj });
+    if ( !asCursor ) {
+      return cursor.toArray()
+    } else {
+      return cursor;
+    };
   }
 
   /**
@@ -400,6 +464,8 @@ class Annotations2 extends CollectionAbstract {
    *   canvasMin: number?,
    *   canvasMax: number?,
    *   onlyIds: boolean
+   *   page: number
+   *   pageSize: number
    * }}
    * @returns {object} annotationList containing results
    */
@@ -410,15 +476,17 @@ class Annotations2 extends CollectionAbstract {
     motivation=undefined,
     canvasMin=undefined,
     canvasMax=undefined,
-    onlyIds=false
+    onlyIds=false,
+    page=1,
+    pageSize=process.env.PAGE_SIZE
   }) {
     const
-      queryBase = { "on.manifestShortId": manifestShortId },
-      queryFilters = { $and: [] };
+      filtersBase = { "on.manifestShortId": manifestShortId },
+      filtersExtra = { $and: [] };
 
     // expand query parameters
     if ( q ) {
-      queryFilters.$and.push({
+      filtersExtra.$and.push({
         $or: [
           { "@id": q },
           { "resource.@id": q },
@@ -427,7 +495,7 @@ class Annotations2 extends CollectionAbstract {
       });
     };
     if ( motivation ) {
-      queryFilters.$and.push(
+      filtersExtra.$and.push(
         motivation === "non-painting"
           ? { motivation: { $ne: "sc:painting" } }
           : motivation === "painting"
@@ -438,10 +506,10 @@ class Annotations2 extends CollectionAbstract {
     if ( !isNaN(canvasMin) ) {
       // if canvasMax is undefined, then search for canvasIdx===canvasMin
       if ( !canvasMax ) {
-        queryFilters.$and.push({ "on.canvasIdx": canvasMin })
+        filtersExtra.$and.push({ "on.canvasIdx": canvasMin })
       // if canvasMin and canvasMax, canvasIdx must be in [canvasMin, canvasMax] (inclusive).
       } else {
-        queryFilters.$and.push({
+        filtersExtra.$and.push({
           $and: [
             { "on.canvasIdx": { $gte: canvasMin } },
             { "on.canvasIdx": { $lte: canvasMax } }
@@ -449,16 +517,22 @@ class Annotations2 extends CollectionAbstract {
         })
       }
     }
-    const query =
-      queryFilters.$and.length
-        ? { ...queryBase, ...queryFilters }
-        : queryBase;
+    const queryFilter =
+      filtersExtra.$and.length
+        ? { ...filtersBase, ...filtersExtra }
+        : filtersBase;
 
     if ( !onlyIds ) {
-      const annotations = await this.find(query);
-      return toAnnotationList(annotations, queryUrl, `search results for query ${queryUrl}`);
+      return await this.#paginate({
+        queryUrl,
+        queryFilter,
+        page,
+        pageSize,
+        label: `Paginated annotation List (page: ${page}, ${pageSize} items per page)`
+      })
     } else {
-      return ( await this.find(query, { "@id": 1 }) )
+      // NOTE: there is no pagination if `onlyIds` is true
+      return ( await this.find(queryFilter, { "@id": 1 }) )
         .map((ann) => ann["@id"]);
     }
   }
@@ -469,11 +543,19 @@ class Annotations2 extends CollectionAbstract {
    * @param {boolean} asAnnotationList
    * @returns
    */
-  async findByCanvasUri(queryUrl, canvasUri, asAnnotationList=false) {
-    const annotations = await this.find({ "on.full": canvasUri });
-    return asAnnotationList
-      ? toAnnotationList(annotations, queryUrl, `annotations targeting canvas ${canvasUri}`)
-      : annotations;
+  async findByCanvasUri({
+    queryUrl,
+    canvasUri,
+    page=1,
+    pageSize=process.env.PAGE_SIZE
+  }) {
+    return this.#paginate({
+      queryUrl,
+      queryFilter: { "on.full": canvasUri },
+      label: `annotations targeting canvas ${canvasUri}`,
+      page,
+      pageSize
+    });
   }
 
   /**