@paulhectork/aiiinotate 0.12.0

package/src/schemas/schemasRoutes.js

@@ -0,0 +1,318 @@
+/**
+ * schemas for routes. these schemas are more permissive than the database schemas, defined for example in `presentation2`.
+ */
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+
+function addSchemas(fastify, makeSchemaUri) {
+
+  ////////////////////////////////////////////////////////
+  // ANNOTATIONS ROUTES
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeAnnotation2"),
+    type: "object",
+    required: [ "@id", "@type", "motivation", "on" ],
+    properties: {
+      "@id": { type: "string" },
+      "@type": { type: "string" },
+      motivation: { anyOf: [
+        { type: "string", enum: [ "oa:Annotation" ] },
+        { type: "array", items: { type: "string" } }
+      ] },
+      on: {
+        anyOf: [
+          { type: "string" },
+          { type: "object" },
+          {
+            type: "array",
+            items: { anyOf: [
+              { type: "string" },
+              { type: "object" }
+            ] },
+            minItems: 1
+          }
+        ]
+      }
+    }
+  });
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeAnnotation3"),
+    type: "object",
+    required: [ "id", "type", "motivation", "target" ],
+    properties: {
+      id: { type: "string" },
+      type: { type: "string", enum: [ "Annotation" ] },
+      motivation: { anyOf: [
+        { type: "string" },
+        { type: "array", items: { type: "string" } },
+      ] },
+      target: {
+        anyOf: [
+          { type: "string" },
+          { type: "object" },
+          {
+            type: "array",
+            items: { anyOf: [
+              { type: "string" },
+              { type: "object" }
+            ] },
+            minItems: 1
+          }
+        ]
+      }
+    }
+  })
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeAnnotation2Or3"),
+    anyOf: [
+      { $ref: makeSchemaUri("routeAnnotation2") },
+      { $ref: makeSchemaUri("routeAnnotation3") }
+    ]
+  });
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeAnnotationListOrPageUri"),
+    type: "object",
+    required: [ "uri" ],
+    properties: {
+      "uri": { type: "string" },
+    }
+  });
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeAnnotationListOrPageUriArray"),
+    type: "array",
+    items: { $ref: "routeAnnotationListOrPageUri" }
+  });
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeAnnotationList"),
+    type: "object",
+    required: [ "@id", "@type", "resources" ],
+    properties: {
+      "@context": { type: "string" },  // i don't specify the value because @context may be an URI that points to a JSON that contains several namespaces other than "http://iiif.io/api/presentation/2/context.json"
+      "@id": { type: "string" },
+      "@type": { type: "string", enum: [ "sc:AnnotationList" ] },
+      "resources": {
+        type: "array",
+        items: { $ref: makeSchemaUri("routeAnnotation2") }
+      }
+    }
+  })
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeAnnotationPage"),
+    type: "object",
+    required: [ "@id", "@type", "items" ],
+    properties: {
+      "@context": { type: "string" },  // i don't specify the value because @context may be an URI that points to a JSON that contains several namespaces other than "http://iiif.io/api/presentation/2/context.json"
+      "id": { type: "string" },
+      "type": { type: "string", enum: [ "AnnotationPage" ] },
+      "items": {
+        type: "array",
+        items: { $ref: makeSchemaUri("routeAnnotation3") }
+      }
+    }
+  });
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeAnnotationListArray"),
+    type: "array",
+    items: { $ref: makeSchemaUri("routeAnnotationList") }
+  });
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeAnnotationPageArray"),
+    type: "array",
+    items: { $ref: makeSchemaUri("routeAnnotationPage") }
+  })
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeAnnotationCreateMany"),
+    anyOf: [
+      { $ref: makeSchemaUri("routeAnnotationList") },
+      { $ref: makeSchemaUri("routeAnnotationPage") },
+      { $ref: makeSchemaUri("routeAnnotationListArray") },
+      { $ref: makeSchemaUri("routeAnnotationPageArray") },
+      { $ref: makeSchemaUri("routeAnnotationListOrPageUri") },
+      { $ref: makeSchemaUri("routeAnnotationListOrPageUriArray") },
+    ]
+  })
+
+  // 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"),
+    oneOf: [
+      {
+        type: "object",
+        required: [ "uri" ],
+        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" } },
+        additionalProperties: false
+      },
+      {
+        type: "object",
+        required: [ "canvasUri" ],
+        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
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeManifest2Or3"),
+    anyOf: [
+      {
+        type: "object",
+        required: [ "uri" ],
+        properties: { uri: { type: "string" } }
+      },
+      { $ref: fastify.schemasPresentation2.makeSchemaUri("manifestPublic") },
+      { $ref: fastify.schemasPresentation3.makeSchemaUri("manifestPublic") },
+    ]
+  });
+
+  // for manifests: key-value pairs to filter a manifests collection by
+  fastify.addSchema({
+    $id: makeSchemaUri("routeManifestFilter"),
+    type: "object",
+    oneOf: [
+      {
+        type: "object",
+        required: [ "uri" ],
+        properties: { uri: { type: "string" } },
+        additionalProperties: false
+      },
+      {
+        type: "object",
+        required: [ "manifestShortId" ],
+        properties: { manifestShortId: { type: "string" } },
+        additionalProperties: false
+      }
+    ]
+  });
+
+  ////////////////////////////////////////////////////////
+  // GENERIC STUFF
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeDelete"),
+    type: "object",
+    oneOf: [
+      { $ref: makeSchemaUri("routeAnnotationFilter") },
+      { $ref: makeSchemaUri("routeManifestFilter") },
+    ]
+  });
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeResponseInsert"),
+    type: "object",
+    required: [ "insertedCount" ],
+    properties: {
+      insertedCount: { type: "integer", minimum: 0 },
+      insertedIds: {
+        type: "array",
+        items: { type: "string" }
+      },
+      preExistingIds: {
+        type: "array",
+        items: { type: "string" }
+      },
+      fetchErrorIds: {
+        type: "array",
+        items: { type: "string" }
+      },
+      rejectedIds: {
+        type: "array",
+        items: { type: "string" }
+      }
+    }
+  });
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeResponseUpdate"),
+    type: "object",
+    required: [ "matchedCount", "modifiedCount", "upsertedCount" ],
+    properties: {
+      matchedCount: { type: "integer" },
+      modifiedCount: { type: "integer" },
+      upsertedCount: { type: "integer" },
+      upsertedId: { type: [ "string", "null" ] }  // string|null => the field is nullable !
+    }
+  });
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeResponseDelete"),
+    type: "object",
+    required: [ "deletedCount" ],
+    properties: {
+      deletedCount: { type: "integer", minimum: 0 }
+    }
+  });
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeResponseError"),
+    type: "object",
+    required: [],// [ "message", "info", "method", "url" ],
+    properties: {
+      message: { type: "string" },
+      info: {},  // only using `{}` equates to JS "Any" type
+      method: { type: "string" },
+      url: { type: "string" },
+      requestBody: {}
+    }
+  });
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeResponseCount"),
+    type: "object",
+    required: [ "count" ],
+    properties: {
+      count: {
+        type: "integer",
+        minimum: 0
+      }
+    }
+  })
+
+  return fastify
+}
+
+
+export default addSchemas;
+

package/src/server.js

@@ -0,0 +1,25 @@
+/**
+ * serve a fastify app
+ */
+
+import build from "#src/app.js";
+import { PORT, HOST } from "#constants";
+
+/**
+ * @param {import("#types").ServeModeType} serveMode
+ */
+async function server (serveMode) {
+  if ([ "dev", "prod" ].includes(serveMode)) {
+    serveMode = "default";
+  }
+
+  const fastify = await build(serveMode);
+  try {
+    fastify.listen({ port: PORT, host: HOST });
+  } catch(err) {
+    fastify.log.error(err);
+    process.exit(1);
+  }
+};
+
+export default server;

package/src/types.js

@@ -0,0 +1,97 @@
+/** @typedef {import("node:test")} NodeTestType */
+
+/** @typedef {import("fastify").FastifyInstance} FastifyInstanceType */
+/** @typedef {import("fastify").FastifyReply} FastifyReplyType */
+/** @typedef {import("fastify").FastifySchema} FastifySchemaType */
+
+/** @typedef {import("mongodb").Db} MongoDbType */
+/** @typedef {import("mongodb").ObjectId } MongoObjectId */
+/** @typedef {import("mongodb").Collection} MongoCollectionType */
+/** @typedef {import("mongodb").InsertManyResult} MongoInsertManyResultType */
+/** @typedef {import("mongodb").InsertOneResult} MongoInsertOneResultType */
+/** @typedef {MongoInsertManyResultType | MongoInsertOneResultType} MongoInsertResultType */
+/** @typedef {import("mongodb").UpdateResult} MongoUpdateResultType */
+/** @typedef {import("mongodb").DeleteResult} MongoDeleteResultType */
+/** @typedef {import("mongodb").MongoClient} MongoClientType */
+/** @typedef {import("mongodb").FindCursor} MongoFindCursorType */
+
+/** @typedef {import("ajv").ValidateFunction} AjvValidateFunctionType */
+
+/** @typedef {"dev"|"prod"} ServeModeType */
+
+/** @typedef {"uri"|"manifestShortId"|"canvasUri"} AnnotationsDeleteKeyType */
+
+/** @typedef {2|3} IiifPresentationVersionType */
+/** @typedef {"manifests2"|"manifests3"|"annotations2"|"annotations3"} CollectionNamesType */
+/**
+ * @typedef InsertResponseType
+ * @type {object}
+ * @property {number} insertedCount - the number of documents that were properly inserted
+ * @property {Array<string|MongoObjectId>} insertedIds - the ids of the documents that were properly inserted
+ * @property {Array<string|MongoObjectId>} [preExistingIds] - the ids of documents that were aldready inserted in a collection with a UNIQUE clause. USED ONLY BY `manifests2` and `manifests3`
+ * @property {Array<string>} [fetchErrorIds] - the ids of referenced documents that could not be fetched. USED ONLY BY `manifests2` and `manifests3`
+ * @property {{ [x: string]: string }} [rejectedIds] - the ids of the documents that did not pass validation, mapped to validation errors. USED ONLY BY `manifests2` and `manifests3`
+ */
+
+/**
+ * @typedef {Array<InsertResponseType>} InsertResponseArrayType
+ */
+
+/**
+ * @typedef UpdateResponseType
+ * @type {object}
+ * @property {number} matchedCount
+ * @property {number} modifiedCount
+ * @property {number} upsertedCount
+ * @property {string?} [upsertedId]
+ */
+
+/**
+ * @typedef DeleteResponseType
+ * @type {object}
+ * @property {number} deletedCount
+ */
+
+/**
+ * @typedef {"read"|"insert"|"update"|"delete"} DataOperationsType
+ *   the allowed mongo operations.
+ */
+
+/**
+ * @typedef Manifest2InternalType
+ *   app and database-side structure of IIIF manifests
+ * @type {object}
+ * @property {string} ["@id"] - the manifest's '@id'
+ * @property {string} manifestShortId
+ * @property {string[]} canvasIds
+ */
+
+/**
+ * @typedef IiifCollection2Type
+ *    IIIF manifests collection
+ * @type {object}
+ * @property {string} ["@context"]
+ * @property {string} ["@id"]
+ * @property {"sc:Collection"} ["@type"]
+ * @property {string?} label
+ * @property {Array<{ "@type": "sc:Manifest", "@id": string }>} members
+ */
+
+/**
+ * @typedef {import("#manifests/manifests2.js").Manifests2InstanceType} Manifests2InstanceType
+ * type of an instance of the Manifests2 class.
+ */
+/**
+ * @typedef {import("#annotations/annotations2.js").Annotations2InstanceType} Annotations2InstanceType
+ * type of an instance of the Annotations2 class.
+ */
+/**
+ * @typedef {import("#manifests/manifests3.js").Manifests3InstanceType} Manifests3InstanceType
+ * type of an instance of the Manifests3 class.
+ */
+/**
+ * @typedef {import("#annotations/annotations3.js").Annotations3InstanceType} Annotations3InstanceType
+ * type of an instance of the Annotations3 class.
+ */
+
+export {}