adapt-authoring-content 3.0.6 → 3.1.0

package/lib/ContentModule.js

@@ -2,7 +2,7 @@ import { AbstractApiModule } from 'adapt-authoring-api'
 import { Hook, stringifyValues } from 'adapt-authoring-core'
 import { createObjectId, parseObjectId } from 'adapt-authoring-mongodb'
 import { ObjectId } from 'mongodb'
-import { ContentTree, computeSortOrderOps, contentTypeToSchemaName, extractAssetIds, formatFriendlyId, parseMaxSeq } from './utils.js'
+import { ContentTree, buildAssetUsagePipeline, computeSortOrderOps, contentTypeToSchemaName, extractAssetIds, formatFriendlyId, parseMaxSeq } from './utils.js'
 /**
  * Module which handles course content
  * @memberof content
@@ -104,6 +104,25 @@ class ContentModule extends AbstractApiModule {
     throw this.app.errors.RESOURCE_IN_USE.setData({ type: 'asset', courses })
   }
 
+  /**
+   * Returns a map of asset _id to the number of distinct courses each asset is referenced by.
+   * Reads the indexed `_assetIds` field. Accepts an optional `assetIds` array in the request body to
+   * scope the counts (e.g. the page of assets shown in the UI); assets with no usage are omitted.
+   * @param {external:ExpressRequest} req
+   * @param {external:ExpressResponse} res
+   * @param {function} next
+   * @return {Promise}
+   */
+  async handleAssetUsage (req, res, next) {
+    try {
+      const assetIds = Array.isArray(req.body?.assetIds) ? req.body.assetIds.map(id => parseObjectId(id)) : undefined
+      const results = await this.mongodb.getCollection(this.collectionName).aggregate(buildAssetUsagePipeline(assetIds)).toArray()
+      res.json(Object.fromEntries(results.map(r => [r._id.toString(), r.courseCount])))
+    } catch (e) {
+      next(e)
+    }
+  }
+
   /** @override */
   async getSchemaName (data) {
     const { contentplugin } = this

package/lib/utils/buildAssetUsagePipeline.js

@@ -0,0 +1,29 @@
+/**
+ * Builds the aggregation pipeline that counts, per asset, how many distinct courses reference it.
+ *
+ * Operates on the content collection's indexed `_assetIds` field (maintained on every content
+ * insert/update). The leading `$match` lets the query use the `_assetIds` index when scoped; the
+ * post-`$unwind` `$match` discards the other asset ids carried by matched documents so only the
+ * requested assets remain. Counting distinct `_courseId` via `$addToSet` (rather than documents)
+ * means an asset referenced by many content items within one course still counts as one course.
+ *
+ * Pure helper extracted from {@link ContentModule#handleAssetUsage} so it can be unit-tested without
+ * booting the app. Asset ids must already be coerced to ObjectId — `getCollection().aggregate()` is
+ * the raw driver and does not normalise ObjectId strings the way the module query layer does.
+ *
+ * @param {Array} [assetIds] Asset ObjectIds to scope the counts to. Omit/empty to count all assets.
+ * @returns {Array<Object>} Aggregation pipeline producing `{ _id: <assetId>, courseCount }` rows
+ * @memberof content
+ */
+export default function buildAssetUsagePipeline (assetIds) {
+  const match = Array.isArray(assetIds) && assetIds.length > 0
+    ? { $match: { _assetIds: { $in: assetIds } } }
+    : null
+  return [
+    ...(match ? [match] : []),
+    { $unwind: '$_assetIds' },
+    ...(match ? [match] : []),
+    { $group: { _id: '$_assetIds', courses: { $addToSet: '$_courseId' } } },
+    { $project: { courseCount: { $size: '$courses' } } }
+  ]
+}

package/lib/utils.js

@@ -1,4 +1,5 @@
 export { default as ContentTree } from './ContentTree.js'
+export { default as buildAssetUsagePipeline } from './utils/buildAssetUsagePipeline.js'
 export { default as computeSortOrderOps } from './utils/computeSortOrderOps.js'
 export { extractAssetIds } from './utils/extractAssetIds.js'
 export { default as contentTypeToSchemaName } from './utils/contentTypeToSchemaName.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-content",
-  "version": "3.0.6",
+  "version": "3.1.0",
   "description": "Module for managing Adapt content",
   "homepage": "https://github.com/adapt-security/adapt-authoring-content",
   "license": "GPL-3.0",

package/routes.json

@@ -110,6 +110,29 @@
           }
         }
       }
+    },
+    {
+      "route": "/assetusage",
+      "handlers": { "post": "handleAssetUsage" },
+      "permissions": { "post": ["read:${scope}"] },
+      "meta": {
+        "post": {
+          "summary": "Count how many distinct courses each asset is used in",
+          "requestBody": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "assetIds": { "type": "array", "items": { "type": "string" }, "description": "Optional list of asset _ids to scope the counts to. Omit to count all assets." }
+                  }
+                }
+              }
+            }
+          },
+          "responses": { "200": { "description": "Object mapping asset _id to the number of distinct courses referencing it; assets with no usage are omitted" } }
+        }
+      }
     }
   ]
 }

package/tests/utils-buildAssetUsagePipeline.spec.js

@@ -0,0 +1,48 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import buildAssetUsagePipeline from '../lib/utils/buildAssetUsagePipeline.js'
+
+const GROUP = { $group: { _id: '$_assetIds', courses: { $addToSet: '$_courseId' } } }
+const PROJECT = { $project: { courseCount: { $size: '$courses' } } }
+
+describe('buildAssetUsagePipeline', () => {
+  for (const [name, input] of [
+    ['no argument', undefined],
+    ['null', null],
+    ['empty array', []]
+  ]) {
+    it(`counts all assets when given ${name} (no $match, single $unwind)`, () => {
+      const pipeline = buildAssetUsagePipeline(input)
+      assert.deepEqual(pipeline, [
+        { $unwind: '$_assetIds' },
+        GROUP,
+        PROJECT
+      ])
+      assert.equal(pipeline.filter(s => s.$match).length, 0)
+    })
+  }
+
+  it('scopes with a $match before and after $unwind when asset ids are given', () => {
+    const ids = ['id-a', 'id-b']
+    const pipeline = buildAssetUsagePipeline(ids)
+    const expectedMatch = { $match: { _assetIds: { $in: ids } } }
+    assert.deepEqual(pipeline, [
+      expectedMatch,
+      { $unwind: '$_assetIds' },
+      expectedMatch,
+      GROUP,
+      PROJECT
+    ])
+  })
+
+  it('places the pre-$unwind $match first so the _assetIds index can be used', () => {
+    const pipeline = buildAssetUsagePipeline(['id-a'])
+    assert.ok(pipeline[0].$match, 'first stage should be a $match')
+    assert.equal(pipeline[1].$unwind, '$_assetIds')
+  })
+
+  it('counts distinct courses (uses $addToSet on _courseId, not a document count)', () => {
+    const group = buildAssetUsagePipeline().find(s => s.$group)
+    assert.deepEqual(group.$group.courses, { $addToSet: '$_courseId' })
+  })
+})