aiiinotate 0.2.0

package/src/schemas/schemasResolver.js

@@ -0,0 +1,71 @@
+import fastifyPlugin from "fastify-plugin";
+
+/**
+ * resolve schemas: convert all references to external schemas to embedded JsonSchemas.
+ *
+ * mongo doesn't implement the whole JSONSchema standard, and in some places in fastify (i.e., routes response schemas), references (`$ref`) are not allowed.
+ * in the app and in this module, our schemas are defined according to the full Fastify implementation, to use the schemas everywhere, we need to convert them.
+ *
+ * conversion primarily means converting all `$ref` references to external schemas to the JsonSchemas referenced.
+ *
+ * JSONSchema has a recursive data model in which a root schema contains  nested schemas in a tree structure. in turn, our conversion function is recursive.
+ *
+ * NOTE: our conversion function DOES NOT DO ALL CONVERSIONS, only what we need.
+ * for example, we suppose that our schemas are built using $ref's to external schemas, and not defining sub-schemas in the `definitions` field.
+ *
+ * see: https://www.mongodb.com/docs/manual/reference/operator/query/jsonSchema/#omissions
+ */
+function schemasResolver (fastify, schema) {
+  const funcName = schemasResolver.name;
+
+  // no need to process strings, booleans or numbers
+  if ( typeof schema==="string" || typeof schema==="number" || typeof schema==="boolean" ) {
+    return schema
+  }
+  // convert each item in arrays
+  else if ( Array.isArray(schema) ) {
+    return schema.map((item) => schemasResolver(fastify, item));
+  }
+  // convert each key-value pair. this is actually the main part that will delta to the above branches.
+  else if ( schema.constructor === Object ) {
+    const out = {};
+
+    for ( let [k,v] of Object.entries(schema) ) {
+      // $id is not allowed => remove it
+      if ( k==="$id" ) {
+        continue
+      }
+      // $refs must be resolved => replace the kv pair { $ref: schemaUri } with the corresponding schemas and process convert those schemas to mongo.
+      else if ( k==="$ref" ) {
+        return schemasResolver(fastify, fastify.getSchema(v))
+      }
+      // convert JsonSchema integer types to bsonType: int
+      else if ( k==="type" && v==="integer" )
+        out.bsonType = "int";
+      // failsafe for other JsonSchema fields that are unimplemented by Mongo.
+      // NOTE: "format" is also a JsonSchema keyword, but the "format" keyword
+      // is used in our annotations, so we don't raise if it is encounetered.
+      // this filter could be fine-tuned to work only at top-level of schemas. for now, we allow "format¨.
+      else if ( ["$schema", "$default", "definitions"].includes(k) ) {
+        throw new Error(`${funcName}: JSONSchema field '${k}' conversion to Mongo schema is not implemented ! in schema: ${schema}`);
+      }
+      // it's a "normal" value => process it.
+      else {
+        out[k] = schemasResolver(fastify, v);
+      }
+    }
+
+    return out;
+  }
+  else {
+    throw new Error(`${funcName}: cannot process unexpected type: '${typeof k}' in schema ${schema}`);
+  }
+}
+
+function schemasResolverPlugin(fastify, options, done) {
+  fastify.decorate("schemasResolver", (schema) => schemasResolver(fastify, schema));
+  done();
+}
+
+export default fastifyPlugin(schemasResolverPlugin);
+

package/src/schemas/schemasRoutes.js

@@ -0,0 +1,277 @@
+/**
+ * schemas for routes. these schemas are more permissive than the database schemas, defined for example in `presentation2`.
+ */
+
+import fastifyPlugin from "fastify-plugin";
+
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+
+
+/** @param {string} slug */
+const makeSchemaUri = (slug) =>
+  `${process.env.APP_BASE_URL}/schemas/routes/${slug}`;
+
+/**
+ * @param {FastifyInstanceType} fastify
+ * @param {"search"|"presentation"} slug
+ */
+const getSchema = (fastify, slug) =>
+  fastify.getSchema(makeSchemaUri(slug));
+
+
+/**
+ *
+ * @param {FastifyInstanceType} fastify
+ * @param {object?} options
+ * @param {function} done
+ */
+function addSchemas(fastify, options, done) {
+
+  ////////////////////////////////////////////////////////
+  // 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" }]}
+    }
+  });
+
+  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" }]}
+    }
+  })
+
+  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") },
+    ]
+  })
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeAnnotationDelete"),
+    oneOf: [
+      {
+        type: "object",
+        required: ["uri"],
+        properties: { uri: { type: "string", description: "delete the annotation with this '@id'" } }
+      },
+      {
+        type: "object",
+        required: ["manifestShortId"],
+        properties: { manifestShortId: { type: "string", description: "delete all annotations for a single manifest" } }
+      },
+      {
+        type: "object",
+        required: ["canvasUri"],
+        properties: { canvasUri: { type: "string", description: "delete all annotations for a single canvas" } }
+      }
+    ]
+  })
+
+  ////////////////////////////////////////////////////////
+  // 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") },
+    ]
+  });
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeManifestDelete"),
+    type: "object",
+    oneOf: [
+      {
+        type: "object",
+        required: ["uri"],
+        properties: { uri: { type: "string" } }
+      },
+      {
+        type: "object",
+        required: ["manifestShortId"],
+        properties: { manifestShortId: { type: "string" } }
+      }
+    ]
+  });
+
+  ////////////////////////////////////////////////////////
+  // GENERIC STUFF
+
+  fastify.addSchema({
+    $id: makeSchemaUri("routeDelete"),
+    type: "object",
+    oneOf: [
+      { $ref: makeSchemaUri("routeAnnotationDelete") },
+      { $ref: makeSchemaUri("routeManifestDelete") },
+    ]
+  });
+
+  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.decorate("schemasRoutes", {
+    makeSchemaUri: makeSchemaUri,
+    getSchema: (slug) => getSchema(fastify, slug)
+  });
+
+  done();
+}
+
+
+export default fastifyPlugin(addSchemas);
+

package/src/server.js

@@ -0,0 +1,22 @@
+/**
+ * serve a fastify app
+ */
+
+import build from "#src/app.js";
+
+/**
+ * @param {object} options
+ */
+async function start (options) {
+
+  const fastify = await build();
+
+  try {
+    fastify.listen({ port: process.env.APP_PORT });
+  } catch(err) {
+    fastify.log.error(err);
+    process.exit(1);
+  }
+};
+
+start();

package/src/types.js

@@ -0,0 +1,93 @@
+/** @typedef {import("node:test")} NodeTestType */
+
+/** @typedef {import("fastify").FastifyInstance} FastifyInstanceType */
+/** @typedef {import("fastify").FastifyReply} FastifyReplyType */
+
+/** @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("ajv").ValidateFunction} AjvValidateFunctionType */
+
+/** @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 {}