adapt-authoring-core 2.2.4 → 2.3.1

package/docs/hooks.md

@@ -8,12 +8,13 @@ A hook is a point in the code where external observers can run their own functio
 
 All hook observers must complete before the operation continues. For example, a document won't be inserted until all `preInsertHook` observers have finished executing.
 
-### Mutable vs. non-mutable
+### Hook types
 
-Hooks can be either **mutable** or **immutable**:
+Hooks support three execution types:
 
-- **Immutable**: the _default_ behaviour. Observers are run in parallel (at the same time). When running in series, observers receive a deep copy of arguments to prevent unintended modifications.
-- **Mutable**: hooks allow modification of param data, and run observers in series (one after another) to ensure modifications are applied in order.
+- **Parallel** (default): observers run at the same time. Observers receive a deep copy of arguments to prevent unintended modifications.
+- **Series**: observers run one after another. When `mutable: true` is set, observers can modify shared arguments in place.
+- **Middleware**: observers wrap a core function using a `next()` pattern (like Express middleware). Each observer receives `(next, ...args)` and must call `next(...args)` to continue the chain. This allows observers to run logic both before and after the core operation, with shared scope across both.
 
 ## Basic usage
 
@@ -32,12 +33,23 @@ class MyModule extends AbstractModule {
 
     // force observers to run in series
     this.mySeriesHook = new Hook({ type: Hook.Types.Series })
+
+    // middleware hook — observers wrap a core function
+    this.myMiddlewareHook = new Hook({ type: Hook.Types.Middleware })
   }
 
   async doSomething () {
     // Invoke the hook, passing any relevant data
     await this.myBasicHook.invoke(someData)
   }
+
+  async doSomethingWrapped (data) {
+    // Invoke middleware hook — first arg is the core function, rest are passed through
+    const coreFn = async (data) => {
+      return await this.db.insert(data)
+    }
+    return this.myMiddlewareHook.invoke(coreFn, data)
+  }
 }
 ```
 
@@ -106,21 +118,24 @@ try {
 
 Below are some commonly used hooks, which you may find useful.
 
-| Module | Hook | Description | Parameters | Mutable |
-| ------ | ---- | ----------- | ---------- | :-----: |
-| AbstractModule | `readyHook` | Module has initialised | | No |
-| AbstractApiModule | `requestHook` | API request received | `(req)` | Yes |
-| AbstractApiModule | `preInsertHook` | Before document insert | `(data, options, mongoOptions)` | Yes |
-| AbstractApiModule | `postInsertHook` | After document insert | `(doc)` | No |
-| AbstractApiModule | `preUpdateHook` | Before document update | `(originalDoc, newData, options, mongoOptions)` | Yes |
-| AbstractApiModule | `postUpdateHook` | After document update | `(originalDoc, updatedDoc)` | No |
-| AbstractApiModule | `preDeleteHook` | Before document delete | `(doc, options, mongoOptions)` | No |
-| AbstractApiModule | `postDeleteHook` | After document delete | `(doc)` | No |
-| AbstractApiModule | `accessCheckHook` | Check document access | `(req, doc)` | No |
-| AdaptFrameworkBuild | `preBuildHook` | Before course build starts | | Yes |
-| AdaptFrameworkBuild | `postBuildHook` | After course build completes | | Yes |
-| AdaptFrameworkModule | `preImportHook` | Before course import starts | | Yes |
-| AdaptFrameworkModule | `postImportHook` | After course import completes | | No |
+| Module | Hook | Description | Parameters | Type |
+| ------ | ---- | ----------- | ---------- | :--: |
+| AbstractModule | `readyHook` | Module has initialised | | Parallel |
+| AbstractApiModule | `requestHook` | API request received | `(req)` | Mutable |
+| AbstractApiModule | `insertHook` | Wraps the insert operation | `(next, data, options, mongoOptions)` | Middleware |
+| AbstractApiModule | `updateHook` | Wraps the update operation | `(next, query, data, options, mongoOptions)` | Middleware |
+| AbstractApiModule | `deleteHook` | Wraps the delete operation | `(next, query, options, mongoOptions)` | Middleware |
+| AbstractApiModule | `preInsertHook` | Before document insert | `(data, options, mongoOptions)` | Mutable |
+| AbstractApiModule | `postInsertHook` | After document insert | `(doc)` | Parallel |
+| AbstractApiModule | `preUpdateHook` | Before document update | `(originalDoc, newData, options, mongoOptions)` | Mutable |
+| AbstractApiModule | `postUpdateHook` | After document update | `(originalDoc, updatedDoc)` | Parallel |
+| AbstractApiModule | `preDeleteHook` | Before document delete | `(doc, options, mongoOptions)` | Parallel |
+| AbstractApiModule | `postDeleteHook` | After document delete | `(doc)` | Parallel |
+| AbstractApiModule | `accessCheckHook` | Check document access | `(req, doc)` | Parallel |
+| AdaptFrameworkBuild | `preBuildHook` | Before course build starts | | Mutable |
+| AdaptFrameworkBuild | `postBuildHook` | After course build completes | | Mutable |
+| AdaptFrameworkModule | `preImportHook` | Before course import starts | | Mutable |
+| AdaptFrameworkModule | `postImportHook` | After course import completes | | Parallel |
 
 ## Practical examples
 
@@ -201,6 +216,54 @@ async init () {
 }
 ```
 
+### Wrapping a CRUD operation (middleware)
+
+Middleware hooks let you run logic both before and after the core operation, with shared scope. This is useful when you need pre-operation state to inform post-operation actions.
+
+```javascript
+async init () {
+  await super.init()
+  const content = await this.app.waitForModule('content')
+
+  content.deleteHook.tap(async (next, query, options, mongoOptions) => {
+    // gather related data BEFORE the delete
+    const item = await content.findOne(query)
+    const related = await this.findRelated(item)
+
+    // run the actual delete
+    const result = await next(query, options, mongoOptions)
+
+    // clean up related data AFTER — item and related are still in scope
+    for (const r of related) {
+      await this.cleanup(r)
+    }
+
+    return result
+  })
+}
+```
+
+You can also use middleware to guard operations. If you don't call `next()`, the operation is blocked:
+
+```javascript
+content.insertHook.tap(async (next, data, options, mongoOptions) => {
+  if (data._restricted) {
+    throw new Error('Cannot insert restricted items')
+  }
+  return next(data, options, mongoOptions)
+})
+```
+
+### Choosing between pre/post hooks and middleware
+
+Use **pre/post hooks** when you only care about one side of an operation — mutating data before a write, or reacting after one. Use **middleware** when you need to own the full lifecycle: gathering state before, acting after, with shared context across both.
+
+Middleware wraps the entire operation including pre/post hooks:
+
+```
+middleware → pre-hook → validate → write → post-hook → middleware returns
+```
+
 ### Waiting for server startup
 
 ```javascript

package/lib/Hook.js

@@ -9,11 +9,13 @@ class Hook {
    * @type {Object}
    * @property {String} Parallel
    * @property {String} Series
+   * @property {String} Middleware
    */
   static get Types () {
     return {
       Parallel: 'parallel',
-      Series: 'series'
+      Series: 'series',
+      Middleware: 'middleware'
     }
   }
 
@@ -69,7 +71,10 @@ class Hook {
   async invoke (...args) {
     let error, data
     try {
-      if (this._options.type === Hook.Types.Parallel) {
+      if (this._options.type === Hook.Types.Middleware) {
+        const [coreFn, ...rest] = args
+        data = await this._invokeMiddleware(coreFn, ...rest)
+      } else if (this._options.type === Hook.Types.Parallel) {
         data = await Promise.all(this._hookObservers.map(o => o(...args)))
       } else {
         // if not mutable, send a deep copy of the args to avoid any meddling
@@ -82,6 +87,29 @@ class Hook {
     if (error) throw error
     return data
   }
+
+  /**
+   * Builds and invokes a middleware chain around a core function.
+   * Each observer receives (next, ...args) and must call next(...args) to continue the chain.
+   * @param {Function} coreFn The core function to wrap
+   * @param {...*} args Arguments to pass through the chain
+   * @return {Promise}
+   */
+  async _invokeMiddleware (coreFn, ...args) {
+    let coreResult
+    const wrappedCoreFn = async (...a) => {
+      coreResult = await coreFn(...a)
+      return coreResult
+    }
+    let fn = wrappedCoreFn
+    for (let i = this._hookObservers.length - 1; i >= 0; i--) {
+      const observer = this._hookObservers[i]
+      const next = fn
+      fn = (...a) => observer(next, ...a)
+    }
+    const result = await fn(...args)
+    return result !== undefined ? result : coreResult
+  }
 }
 
 export default Hook

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-core",
-  "version": "2.2.4",
+  "version": "2.3.1",
   "description": "A bundle of reusable 'core' functionality",
   "homepage": "https://github.com/adapt-security/adapt-authoring-core",
   "license": "GPL-3.0",

package/tests/Hook.spec.js

@@ -11,11 +11,13 @@ describe('Hook', () => {
     it('should expose Series type', () => {
       assert.equal(Hook.Types.Series, 'series')
     })
-  })
 
-  describe('.Types', () => {
-    it('should have exactly two type keys', () => {
-      assert.equal(Object.keys(Hook.Types).length, 2)
+    it('should expose Middleware type', () => {
+      assert.equal(Hook.Types.Middleware, 'middleware')
+    })
+
+    it('should have exactly three type keys', () => {
+      assert.equal(Object.keys(Hook.Types).length, 3)
     })
   })
 
@@ -342,6 +344,176 @@ describe('Hook', () => {
         assert.deepEqual(arr, [1, 2, 3])
       })
     })
+
+    describe('middleware hooks', () => {
+      it('should call the core function when no observers', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        let called = false
+        const core = async () => { called = true; return 'result' }
+        const result = await hook.invoke(core)
+        assert.equal(called, true)
+        assert.equal(result, 'result')
+      })
+
+      it('should pass arguments through to the core function', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        let receivedArgs
+        const core = async (...args) => { receivedArgs = args }
+        await hook.invoke(core, 'a', 'b', 'c')
+        assert.deepEqual(receivedArgs, ['a', 'b', 'c'])
+      })
+
+      it('should wrap the core function with a single observer', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        const order = []
+        hook.tap(async (next, arg) => {
+          order.push('before')
+          const result = await next(arg)
+          order.push('after')
+          return result
+        })
+        const core = async (arg) => { order.push('core'); return arg }
+        await hook.invoke(core, 'data')
+        assert.deepEqual(order, ['before', 'core', 'after'])
+      })
+
+      it('should return the core function result through the chain', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        hook.tap(async (next, val) => next(val))
+        const core = async (val) => val * 2
+        const result = await hook.invoke(core, 5)
+        assert.equal(result, 10)
+      })
+
+      it('should execute multiple observers in order', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        const order = []
+        hook.tap(async (next, arg) => {
+          order.push('outer-before')
+          const result = await next(arg)
+          order.push('outer-after')
+          return result
+        })
+        hook.tap(async (next, arg) => {
+          order.push('inner-before')
+          const result = await next(arg)
+          order.push('inner-after')
+          return result
+        })
+        const core = async () => { order.push('core') }
+        await hook.invoke(core)
+        assert.deepEqual(order, ['outer-before', 'inner-before', 'core', 'inner-after', 'outer-after'])
+      })
+
+      it('should allow observers to modify arguments before core', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        hook.tap(async (next, data) => next({ ...data, extra: true }))
+        let received
+        const core = async (data) => { received = data; return data }
+        await hook.invoke(core, { original: true })
+        assert.deepEqual(received, { original: true, extra: true })
+      })
+
+      it('should allow observers to modify the return value after core', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        hook.tap(async (next, val) => {
+          const result = await next(val)
+          return result + ' modified'
+        })
+        const core = async (val) => val
+        const result = await hook.invoke(core, 'original')
+        assert.equal(result, 'original modified')
+      })
+
+      it('should allow an observer to short-circuit without calling next', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        let coreCalled = false
+        hook.tap(async () => 'blocked')
+        const core = async () => { coreCalled = true; return 'core' }
+        const result = await hook.invoke(core)
+        assert.equal(coreCalled, false)
+        assert.equal(result, 'blocked')
+      })
+
+      it('should propagate errors from the core function', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        hook.tap(async (next) => next())
+        const core = async () => { throw new Error('core error') }
+        await assert.rejects(hook.invoke(core), { message: 'core error' })
+      })
+
+      it('should propagate errors from observers', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        hook.tap(async () => { throw new Error('observer error') })
+        const core = async () => 'ok'
+        await assert.rejects(hook.invoke(core), { message: 'observer error' })
+      })
+
+      it('should allow observer to catch and handle core errors', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        hook.tap(async (next) => {
+          try {
+            return await next()
+          } catch {
+            return 'recovered'
+          }
+        })
+        const core = async () => { throw new Error('fail') }
+        const result = await hook.invoke(core)
+        assert.equal(result, 'recovered')
+      })
+
+      it('should support shared state between before and after phases', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        hook.tap(async (next, data) => {
+          const snapshot = { ...data }
+          const result = await next(data)
+          return { result, snapshot }
+        })
+        const core = async (data) => { data.mutated = true; return data }
+        const output = await hook.invoke(core, { value: 1 })
+        assert.deepEqual(output.snapshot, { value: 1 })
+        assert.equal(output.result.mutated, true)
+      })
+
+      it('should handle sync observers', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        hook.tap((next, val) => next(val))
+        const core = (val) => val + 1
+        const result = await hook.invoke(core, 1)
+        assert.equal(result, 2)
+      })
+
+      it('should fall back to core result when observer calls next() without returning', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        hook.tap(async (next, val) => {
+          await next(val) // calls next but doesn't return the result
+        })
+        const core = async (val) => val * 3
+        const result = await hook.invoke(core, 7)
+        assert.equal(result, 21)
+      })
+
+      it('should fall back to core result through multiple non-returning observers', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        hook.tap(async (next, val) => { await next(val) })
+        hook.tap(async (next, val) => { await next(val) })
+        const core = async (val) => ({ id: val })
+        const result = await hook.invoke(core, 42)
+        assert.deepEqual(result, { id: 42 })
+      })
+
+      it('should prefer explicit observer return over core result fallback', async () => {
+        const hook = new Hook({ type: Hook.Types.Middleware })
+        hook.tap(async (next, val) => {
+          await next(val)
+          return 'transformed'
+        })
+        const core = async (val) => val
+        const result = await hook.invoke(core, 'original')
+        assert.equal(result, 'transformed')
+      })
+    })
   })
 
   describe('#onInvoke()', () => {