adapt-authoring-mongodb 1.1.0 → 1.1.2

package/.github/workflows/new.yml

@@ -1,19 +1,15 @@
-name: Add to main project
+# Calls the org-level reusable workflow to add PRs to the TODO Board
+
+name: Add PR to Project
 
 on:
-  issues:
-    types:
-      - opened
   pull_request:
     types:
       - opened
+      - reopened
 
 jobs:
   add-to-project:
-    name: Add to main project
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/add-to-project@v0.1.0
-        with:
-          project-url: https://github.com/orgs/adapt-security/projects/5
-          github-token: ${{ secrets.PROJECTS_SECRET }}
+    uses: adapt-security/.github/.github/workflows/new.yml@main
+    secrets:
+      PROJECTS_SECRET: ${{ secrets.PROJECTS_SECRET }}

package/.github/workflows/releases.yml

@@ -3,10 +3,16 @@ on:
   push:
     branches:
       - master
+
 jobs:
   release:
     name: Release
     runs-on: ubuntu-latest
+    permissions:
+      contents: write # to be able to publish a GitHub release
+      issues: write # to be able to comment on released issues
+      pull-requests: write # to be able to comment on released pull requests
+      id-token: write # to enable use of OIDC for trusted publishing and npm provenance
     steps:
       - name: Checkout
         uses: actions/checkout@v3
@@ -16,10 +22,11 @@ jobs:
         uses: actions/setup-node@v3
         with:
           node-version: 'lts/*'
+      - name: Update npm
+        run: npm install -g npm@latest
       - name: Install dependencies
         run: npm ci
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.AAT_NPM_TOKEN }}
-        run: npx semantic-release
+        run: npx semantic-release

package/adapt-authoring.json

@@ -3,7 +3,7 @@
   "documentation": {
     "enable": true,
     "manualPages": {
-      "using-mongodb.md": "basics"
+      "using-mongodb.md": "development"
     }
   }
 }

package/docs/using-mongodb.md

@@ -1,66 +1,254 @@
 # Using MongoDB
-The `adapt-authoring-mongodb` module adds the ability to work with MongoDB databases.
+> This guide assumes you have a working MongoDB instance. See the [installation guide](install) for more information.
+---
 
-## Installing MongoDB
-To save data with the authoring tool, you'll need either a local MongoDB install, or a hosted solution.
+The Adapt authoring tool provides two ways to interact with a MongoDB database:
 
-If you're new to hosting web applications/MongoDB and are intending to make your install accessible via the internet, we'd suggest going with a hosted solution.
+1. Via functions inherited from **AbstractApiModule** - _recommended for most use cases_
+2. Directly via **MongoDBModule**
 
-For instructions on installing MongoDB, see the [MongoDB docs](https://docs.mongodb.com/manual/installation/#mongodb-community-edition-installation-tutorials).
+### Which approach should I use?
 
-## Using the module
-The `adapt-authoring-mongodb` module uses MongoDB's [Node.js driver](https://mongodb.github.io/node-mongodb-native/4.2) behind-the-scenes for communicating with MongoDB.
+Use `AbstractApiModule` when you're building a full-featured API module that manages a collection of documents. It provides various functionality by default, such as schema validation, lifecycle hooks, caching, and automatic REST endpoint generation.
 
-Where possible, the MongoDBModule API has been designed to mirror the MongoDB Node.js driver API in both naming convensions and parameter naming/order. In some cases this has been changed for ease-of-use (e.g. `insertOne` has been renamed to `insert`). Please see the [Adapt authoring reference for the MongoDBModule](/class/node_modules/adapt-authoring-mongodb/lib/MongoDBModule.js~MongoDBModule.html) for more information (details on which of the MongoDB Node.js driver functions are used is specified there).
+Use `MongoDBModule` directly when you don't need the extra functionality provided by `AbstractApiModule`, need low-level database access, such as aggregation pipelines, bulk operations, or working with collections outside your module's scope.
 
-> If you're new to working with MongoDB, check out this [Quick Start](https://mongodb.github.io/node-mongodb-native/4.2/#quick-start) guide in the official docs for a good overview.
+---
 
-### Basic use
-The following functions provide the most common functionality, and will likely be the functions you use most often. Please see the [API reference]([/class/node_modules/adapt-authoring-mongodb/lib/MongoDBModule.js~MongoDBModule.html](https://tomtaylor.codes/ls/jsdoc3/MongoDBModule.html)) for full details.
+## Using AbstractApiModule
 
-#### `find(collectionName, query, options)`
-Retrieves a document.
+If your module extends `AbstractApiModule`, you get a complete set of database operations with built-in validation and hooks.
 
-#### `insert(collectionName, data, options)`
-Inserts a new document.
+### Inserting documents
 
-#### `replace(collectionName, query, data, options)`
-Completely replaces an existing document.
+```javascript
+// Validates and inserts a new document. Returns the inserted document.
+const doc = await this.insert({ title: 'My Document', status: 'draft' }, { schemaName: 'myresource' })
+```
+
+### Querying documents
+
+```javascript
+/**
+* find()
+* Returns an array of documents matching the query (empty if no matches are found)
+*/
 
-#### `update(collectionName, query, data, options)`
-Updates only specific fields of an existing document.
+// Find all
+const docs = await this.find()
 
-#### `delete(collectionName, query, options)`
-Removes an existing document.
+// Find with query
+const drafts = await this.find({ status: 'draft' })
 
-### Querying the database
-The `find` function is used to retrieve documents from the database.
+// Find with pagination
+const page = await this.find({}, {}, { limit: 10, skip: 20 })
 
 
-#### Examples
-Note that the MongoDB module, as with the rest of the application, makes heavy use of promises, and will return a pending Promise for all relevant functions.
+/**
+* findOne()
+* Returns single document matching the query
+* if the strict option is NOT set to false, an error will be thrown if no results are found
+*/
 
-Inserting a document into the 'test' collection:
+const doc = await this.findOne({ _id: '507f1f77bcf86cd799439011' })
+
+// Allow no results (returns undefined instead of throwing)
+const doc = await this.findOne({ _id: id }, { strict: false })
 ```
-try {
-  const data = await mongodb.insert('test', { hello: 'world' });
-} catch(e) {
-  // handle error
-}
+
+### Updating documents
+
+```javascript
+// Update a single document
+const updated = await this.update({ _id: '507f1f77bcf86cd799439011' }, { status: 'published' })
+
+// Perform a raw update (gives direct access to extra MongoDB update functionality)
+const updated = await this.update({ _id: id }, { $inc: { viewCount: 1 } }, { rawUpdate: true })
+
+// Update all documents which match a query
+const updated = await this.updateMany({ status: 'draft' }, { status: 'archived' })
+```
+
+### Deleting documents
+
+```javascript
+// Remove a single document. Returns the deleted document
+const deleted = await this.delete({ _id: '507f1f77bcf86cd799439011' })
+
+// Remove multiple documents. Returns an array of deleted documents
+const deleted = await this.deleteMany({ status: 'archived' })
+```
+
+
+### Options reference
+
+The following options can be specified when using the above functions. If the option relates to specific functions, this has been noted.
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `schemaName` | String | Schema to validate against (defaults to module's schema) |
+| `collectionName` | String | Collection to operate on (defaults to module's collection) |
+| `validate` | Boolean | Whether to validate data (default: `true`) |
+| `invokePreHook` | Boolean | Whether to invoke pre-operation hooks (default: `true`) |
+| `invokePostHook` | Boolean | Whether to invoke post-operation hooks (default: `true`) |
+| `rawUpdate` | Boolean | **For `update`/`updateMany`**: pass data directly to MongoDB without wrapping in `$set` |
+| `strict` | Boolean | **For `findOne`**: throw error if no document found (default: `true`) |
+
+### Lifecycle hooks
+
+In addition to the CRUD functions, `AbstractApiModule` provides hooks that allow you to intercept and modify data at various points. These hooks are accessible both internally and externally (i.e. from other modules).
+
+For more detail on the hook system, see this [page](hooks).
+
+| Hook | Parameters | Mutable | Description |
+| ---- | ---------- | :-----: | ----------- |
+| `preInsertHook` | `(data, options, mongoOptions)` | Yes | Before insert |
+| `postInsertHook` | `(doc)` | No | After insert |
+| `preUpdateHook` | `(originalDoc, newData, options, mongoOptions)` | Yes | Before update |
+| `postUpdateHook` | `(originalDoc, updatedDoc)` | No | After update |
+| `preDeleteHook` | `(doc, options, mongoOptions)` | No | Before delete |
+| `postDeleteHook` | `(doc)` | No | After delete |
+
+### Examples
+
+```javascript
+// INTERNAL: Modify data before insert
+this.preInsertHook.tap(data => {
+  data.createdAt = new Date()
+})
+
+// EXTERNAL: React after insert
+mymodule.postInsertHook.tap(doc => {
+  this.log('info', `mymodule created document ${doc._id}`)
+})
 ```
 
-### Advanced use
-It is possible to access the Node.js driver API directly from the MongoDBModule instance to allow for extra functionality not covered by the MongoDBModule itself. An example of this being creating an aggregation pipeline.
+---
+
+## Using MongoDBModule directly
 
-There are two methods of accessing the driver API. Which one you use is entirely up to you, and mostly comes down to code brevity:
-- Using the MongoDB client instance [[Adapt docs](https://tomtaylor.codes/ls/jsdoc3/MongoDBModule.html#client), [MongoDB Node.js driver docs](https://mongodb.github.io/node-mongodb-native/3.6/api/MongoClient.html)]
-- Using the MongoDB collection [[Adapt docs](), [MongoDB Node.js driver docs](https://tomtaylor.codes/ls/jsdoc3/MongoDBModule.html#getCollection)]
+For operations not covered by `AbstractApiModule`, use the MongoDB module directly.
 
+Note that this module follows the MongoDB Node.js driver API fairly closely. As such, there are some (less user-friendly) differences between the functions found in `AbstractApiModule`.
+
+**Warning:** the `mongodb` module provides low-level access to the database, and does not perform any tasks such as data validation. Proceed with caution.
+
+### Accessing the mongodb module
+
+```javascript
+const mongodb = await this.app.waitForModule('mongodb')
 ```
-// using the client instance
-mongodb.client.db.collection('mycollection').aggregate(/* args */)
-// using MongoDBModule#getCollection
-mongodb.getCollection('mycollection').aggregate(/* args */)
+
+### Inserting documents
+
+```javascript
+const doc = await mongodb.insert('users', { email: 'user@example.com', name: 'Test User' })
 ```
 
-See the [MongoDB Node.js driver docs](https://mongodb.github.io/node-mongodb-native/4.2/classes/Collection.html) for the full API.
+### Querying documents
+
+```javascript
+// Find all
+const allUsers = await mongodb.find('users')
+
+// Find with query
+const user = await mongodb.find('users', { email: 'user@example.com' })
+
+// Find with options
+const page = await mongodb.find('users', {}, { limit: 10, skip: 20, sort: { createdAt: -1 }})
+```
+
+### Updating documents
+
+```javascript
+// Update a single document
+const updated = await mongodb.update('users', { _id: '507f1f77bcf86cd799439011' }, { $set: { name: 'Updated Name' } })
+
+// Update multiple documents
+const updated = await mongodb.updateMany('users', { role: 'guest' }, { $set: { active: false } })
+
+// Replace an entire document
+const replaced = await mongodb.replace('users', { _id: '507f1f77bcf86cd799439011' }, { ...data })
+```
+
+### Deleting documents
+
+```javascript
+// Remove a single document
+await mongodb.delete('users', { _id: '507f1f77bcf86cd799439011' })
+
+// Removing multiple documents
+await mongodb.deleteMany('users', { active: false })
+```
+
+### Advanced operations
+
+For aggregation pipelines and other advanced features, access the underlying driver:
+
+```javascript
+// Get a collection reference
+const collection = mongodb.getCollection('users')
+
+// Aggregation pipeline
+const results = await collection.aggregate([
+  { $match: { active: true } },
+  { $group: { _id: '$role', count: { $sum: 1 } } }
+]).toArray()
+
+// Database statistics
+const stats = await mongodb.client.db().stats()
+```
+
+### Working with ObjectIds
+
+The module automatically converts string IDs to ObjectIds. You can also work with them directly:
+
+```javascript
+// Create a new ObjectId
+const id = mongodb.ObjectId.create()
+
+// Check if a string is valid
+const isValid = mongodb.ObjectId.isValid('507f1f77bcf86cd799439011')
+
+// Parse a string to ObjectId
+const objectId = mongodb.ObjectId.parse('507f1f77bcf86cd799439011')
+```
+
+### Indexes
+
+Set indexes for better query performance:
+
+```javascript
+// Simple unique index
+await mongodb.setIndex('users', 'email', { unique: true })
+
+// Compound index
+await mongodb.setIndex('content', { courseId: 1, type: 1 })
+```
+
+See the [MongoDB Node.js driver documentation](https://mongodb.github.io/node-mongodb-native/) for the full driver API.
+
+---
+
+## Error handling
+
+Common database errors:
+
+| Error | Description |
+| ----- | ----------- |
+| `MONGO_CONN_FAILED` | Failed to connect to the database |
+| `MONGO_DUPL_INDEX` | Duplicate key violation (unique index) |
+| `MONGO_IMMUTABLE_FIELD` | Attempted to modify an immutable field |
+| `INVALID_OBJECTID` | Invalid ObjectId string format |
+| `NOT_FOUND` | Document not found (AbstractApiModule only) |
+| `TOO_MANY_RESULTS` | Multiple documents found when one expected |
+
+```javascript
+try {
+  await this.insert({ email: 'existing@example.com' })
+} catch (e) {
+  if (e.code === 'MONGO_DUPL_INDEX') {
+    // Handle duplicate
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-mongodb",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Module for saving to a MongoDB instance",
   "homepage": "https://github.com/adapt-security/adapt-authoring-mongodb",
   "license": "GPL-3.0",
@@ -8,21 +8,21 @@
   "main": "index.js",
   "repository": "github:adapt-security/adapt-authoring-mongodb",
   "dependencies": {
-    "mongodb": "^6.7.0"
+    "mongodb": "^7.0.0"
   },
   "peerDependencies": {
     "adapt-authoring-core": "github:adapt-security/adapt-authoring-core"
   },
   "devDependencies": {
-    "standard": "^17.1.0",
-    "@semantic-release/commit-analyzer": "^9.0.2",
+    "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^8.0.5",
-    "@semantic-release/npm": "^9.0.1",
-    "@semantic-release/release-notes-generator": "^10.0.3",
-    "conventional-changelog-eslint": "^3.0.9",
-    "semantic-release": "^21.0.1",
-    "semantic-release-replace-plugin": "^1.2.7"
+    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/npm": "^13.1.2",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "conventional-changelog-eslint": "^6.0.0",
+    "semantic-release": "^25.0.2",
+    "semantic-release-replace-plugin": "^1.2.7",
+    "standard": "^17.1.0"
   },
   "release": {
     "plugins": [

package/.github/workflows/labelled_prs.yml

@@ -1,16 +0,0 @@
-name: Add labelled PRs to project
-
-on:
-  pull_request:
-    types: [ labeled ]
-
-jobs:
-  add-to-project:
-    if: ${{ github.event.label.name == 'dependencies' }}
-    name: Add to main project
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/add-to-project@v0.1.0
-        with:
-          project-url: https://github.com/orgs/adapt-security/projects/5
-          github-token: ${{ secrets.PROJECTS_SECRET }}