adapt-authoring-api 0.0.1 → 1.0.0

package/lib/AbstractApiUtils.js

@@ -1,145 +1,145 @@
-/**
- * Utilities for APIs
- * @memberof api
- */
-class AbstractApiUtils {
-  /**
-   * Converts HTTP methods to a corresponding 'action' for use in auth
-   * @param {String} method The HTTP method
-   * @return {String}
-   */
-  static httpMethodToAction (method) {
-    switch (method.toLowerCase()) {
-      case 'get':
-        return 'read'
-      case 'post':
-      case 'put':
-      case 'patch':
-      case 'delete':
-        return 'write'
-      default:
-        return ''
-    }
-  }
-
-  /**
-   * Converts HTTP methods to a corresponding database function
-   * @param {String} method The HTTP method
-   * @return {String}
-   */
-  static httpMethodToDBFunction (method) {
-    switch (method.toLowerCase()) {
-      case 'post': return 'insert'
-      case 'get': return 'find'
-      case 'put': case 'patch': return 'update'
-      case 'delete': return 'delete'
-      default: return ''
-    }
-  }
-
-  /**
-   * Generates a list of arguments to be passed to the MongoDBModule from a request object
-   * @param {external:ExpressRequest} req
-   * @return {Array<*>}
-   */
-  static argsFromReq (req) {
-    const opts = { schemaName: req.apiData.schemaName, collectionName: req.apiData.collectionName }
-    switch (req.method) {
-      case 'GET': case 'DELETE':
-        return [req.apiData.query, opts]
-      case 'POST':
-        return [req.apiData.data, opts]
-      case 'PUT': case 'PATCH':
-        return [req.apiData.query, req.apiData.data, opts]
-    }
-  }
-
-  /**
-   * Generates REST API metadata and stores on route config
-   * @param {AbstractApiModule} instance The current AbstractApiModule instance
-   */
-  static generateApiMetadata (instance) {
-    const getData = isList => {
-      const $ref = { $ref: `#/components/schemas/${instance.schemaName}` }
-      return {
-        description: `The ${instance.schemaName} data`,
-        content: { 'application/json': { schema: isList ? { type: 'array', items: $ref } : $ref } }
-      }
-    }
-    const queryParams = [
-      {
-        name: 'limit',
-        in: 'query',
-        description: `How many results should be returned Default value is ${instance.app.config.get('adapt-authoring-api.defaultPageSize')} (max value is ${instance.app.config.get('adapt-authoring-api.maxPageSize')})`
-      },
-      {
-        name: 'page',
-        in: 'query',
-        description: 'The page of results to return (determined from the limit value)'
-      }
-    ]
-    const verbMap = {
-      put: 'Replace',
-      get: 'Retrieve',
-      patch: 'Update',
-      delete: 'Delete',
-      post: 'Insert'
-    }
-    instance.routes.forEach(r => {
-      r.meta = {}
-      Object.keys(r.handlers).forEach(method => {
-        let summary, parameters, requestBody, responses
-        switch (r.route) {
-          case '/':
-            if (method === 'post') {
-              summary = `${verbMap.post} a new ${instance.schemaName} document`
-              requestBody = getData()
-              responses = { 201: getData() }
-            } else {
-              summary = `${verbMap.get} all ${instance.collectionName} documents`
-              parameters = queryParams
-              responses = { 200: getData(true) }
-            }
-            break
-
-          case '/:_id':
-            summary = `${verbMap[method]} an existing ${instance.schemaName} document`
-            requestBody = method === 'put' || method === 'patch' ? getData() : method === 'delete' ? undefined : {}
-            responses = { [method === 'delete' ? 204 : 200]: getData() }
-            break
-
-          case '/query':
-            summary = `Query all ${instance.collectionName}`
-            parameters = queryParams
-            responses = { 200: getData(true) }
-            break
-
-          case '/schema':
-            summary = `Retrieve ${instance.schemaName} schema`
-            break
-        }
-        r.meta[method] = { summary, parameters, requestBody, responses }
-      })
-    })
-  }
-
-  /**
-   * Clones an object and converts any Dates and ObjectIds to Strings
-   * @param {Object} data
-   * @returns A clone object with stringified ObjectIds
-   */
-  static stringifyValues (data) {
-    return Object.entries(data).reduce((cloned, [key, val]) => {
-      const type = val?.constructor?.name
-      cloned[key] =
-        type === 'Date' || type === 'ObjectId'
-          ? val.toString()
-          : type === 'Array' || type === 'Object'
-            ? this.stringifyValues(val)
-            : val
-      return cloned
-    }, Array.isArray(data) ? [] : {})
-  }
-}
-
-export default AbstractApiUtils
+/**
+ * Utilities for APIs
+ * @memberof api
+ */
+class AbstractApiUtils {
+  /**
+   * Converts HTTP methods to a corresponding 'action' for use in auth
+   * @param {String} method The HTTP method
+   * @return {String}
+   */
+  static httpMethodToAction (method) {
+    switch (method.toLowerCase()) {
+      case 'get':
+        return 'read'
+      case 'post':
+      case 'put':
+      case 'patch':
+      case 'delete':
+        return 'write'
+      default:
+        return ''
+    }
+  }
+
+  /**
+   * Converts HTTP methods to a corresponding database function
+   * @param {String} method The HTTP method
+   * @return {String}
+   */
+  static httpMethodToDBFunction (method) {
+    switch (method.toLowerCase()) {
+      case 'post': return 'insert'
+      case 'get': return 'find'
+      case 'put': case 'patch': return 'update'
+      case 'delete': return 'delete'
+      default: return ''
+    }
+  }
+
+  /**
+   * Generates a list of arguments to be passed to the MongoDBModule from a request object
+   * @param {external:ExpressRequest} req
+   * @return {Array<*>}
+   */
+  static argsFromReq (req) {
+    const opts = { schemaName: req.apiData.schemaName, collectionName: req.apiData.collectionName }
+    switch (req.method) {
+      case 'GET': case 'DELETE':
+        return [req.apiData.query, opts]
+      case 'POST':
+        return [req.apiData.data, opts]
+      case 'PUT': case 'PATCH':
+        return [req.apiData.query, req.apiData.data, opts]
+    }
+  }
+
+  /**
+   * Generates REST API metadata and stores on route config
+   * @param {AbstractApiModule} instance The current AbstractApiModule instance
+   */
+  static generateApiMetadata (instance) {
+    const getData = isList => {
+      const $ref = { $ref: `#/components/schemas/${instance.schemaName}` }
+      return {
+        description: `The ${instance.schemaName} data`,
+        content: { 'application/json': { schema: isList ? { type: 'array', items: $ref } : $ref } }
+      }
+    }
+    const queryParams = [
+      {
+        name: 'limit',
+        in: 'query',
+        description: `How many results should be returned Default value is ${instance.app.config.get('adapt-authoring-api.defaultPageSize')} (max value is ${instance.app.config.get('adapt-authoring-api.maxPageSize')})`
+      },
+      {
+        name: 'page',
+        in: 'query',
+        description: 'The page of results to return (determined from the limit value)'
+      }
+    ]
+    const verbMap = {
+      put: 'Replace',
+      get: 'Retrieve',
+      patch: 'Update',
+      delete: 'Delete',
+      post: 'Insert'
+    }
+    instance.routes.forEach(r => {
+      r.meta = {}
+      Object.keys(r.handlers).forEach(method => {
+        let summary, parameters, requestBody, responses
+        switch (r.route) {
+          case '/':
+            if (method === 'post') {
+              summary = `${verbMap.post} a new ${instance.schemaName} document`
+              requestBody = getData()
+              responses = { 201: getData() }
+            } else {
+              summary = `${verbMap.get} all ${instance.collectionName} documents`
+              parameters = queryParams
+              responses = { 200: getData(true) }
+            }
+            break
+
+          case '/:_id':
+            summary = `${verbMap[method]} an existing ${instance.schemaName} document`
+            requestBody = method === 'put' || method === 'patch' ? getData() : method === 'delete' ? undefined : {}
+            responses = { [method === 'delete' ? 204 : 200]: getData() }
+            break
+
+          case '/query':
+            summary = `Query all ${instance.collectionName}`
+            parameters = queryParams
+            responses = { 200: getData(true) }
+            break
+
+          case '/schema':
+            summary = `Retrieve ${instance.schemaName} schema`
+            break
+        }
+        r.meta[method] = { summary, parameters, requestBody, responses }
+      })
+    })
+  }
+
+  /**
+   * Clones an object and converts any Dates and ObjectIds to Strings
+   * @param {Object} data
+   * @returns A clone object with stringified ObjectIds
+   */
+  static stringifyValues (data) {
+    return Object.entries(data).reduce((cloned, [key, val]) => {
+      const type = val?.constructor?.name
+      cloned[key] =
+        type === 'Date' || type === 'ObjectId'
+          ? val.toString()
+          : type === 'Array' || type === 'Object'
+            ? this.stringifyValues(val)
+            : val
+      return cloned
+    }, Array.isArray(data) ? [] : {})
+  }
+}
+
+export default AbstractApiUtils

package/lib/DataCache.js

@@ -1,46 +1,46 @@
-import { App } from 'adapt-authoring-core'
-/**
- * Time-limited data cache
- * @memberof api
- */
-class DataCache {
-  /** @override */
-  constructor ({ enable, lifespan }) {
-    this.isEnabled = enable !== false
-    this.lifespan = lifespan ?? App.instance.config.get('adapt-authoring-api.defaultCacheLifespan')
-    this.cache = {}
-  }
-
-  /**
-   * Retrieve cached data, or run fresh query if no cache exists or cache is invalid
-   * @param {Object} query
-   * @param Object} options
-   * @param {Object} mongoOptions
-   * @returns {*} The cached data
-   */
-  async get (query, options, mongoOptions) {
-    const key = JSON.stringify(query) + JSON.stringify(options) + JSON.stringify(mongoOptions)
-    this.prune()
-    if (this.cache[key]) {
-      return this.cache[key].data
-    }
-    const mongodb = await App.instance.waitForModule('mongodb')
-    const data = await mongodb.find(options.collectionName, query, mongoOptions)
-    this.cache[key] = { data, timestamp: Date.now() }
-    return data
-  }
-
-  /**
-   * Removes invalid cache data
-   */
-  prune () {
-    Object.keys(this.cache).forEach(k => {
-      const cache = this.cache[k]
-      if (Date.now() > (cache.timestamp + this.lifespan)) {
-        delete this.cache[k]
-      }
-    })
-  }
-}
-
-export default DataCache
+import { App } from 'adapt-authoring-core'
+/**
+ * Time-limited data cache
+ * @memberof api
+ */
+class DataCache {
+  /** @override */
+  constructor ({ enable, lifespan }) {
+    this.isEnabled = enable !== false
+    this.lifespan = lifespan ?? App.instance.config.get('adapt-authoring-api.defaultCacheLifespan')
+    this.cache = {}
+  }
+
+  /**
+   * Retrieve cached data, or run fresh query if no cache exists or cache is invalid
+   * @param {Object} query
+   * @param Object} options
+   * @param {Object} mongoOptions
+   * @returns {*} The cached data
+   */
+  async get (query, options, mongoOptions) {
+    const key = JSON.stringify(query) + JSON.stringify(options) + JSON.stringify(mongoOptions)
+    this.prune()
+    if (this.cache[key]) {
+      return this.cache[key].data
+    }
+    const mongodb = await App.instance.waitForModule('mongodb')
+    const data = await mongodb.find(options.collectionName, query, mongoOptions)
+    this.cache[key] = { data, timestamp: Date.now() }
+    return data
+  }
+
+  /**
+   * Removes invalid cache data
+   */
+  prune () {
+    Object.keys(this.cache).forEach(k => {
+      const cache = this.cache[k]
+      if (Date.now() > (cache.timestamp + this.lifespan)) {
+        delete this.cache[k]
+      }
+    })
+  }
+}
+
+export default DataCache

package/lib/typedefs.js

@@ -1,67 +1,67 @@
-/**
- * This file exists to define the below types for documentation purposes.
- */
-/**
- * For AbstractApiModule subclasses the Express ClientRequest object is given an extra apiData property which contains useful data related to the incoming request.
- * Extends Route definition with additional API-specific attributes
- * @memberof api
- * @typedef {Object} ApiRequestData
- * @property {Object} config The API route's config data. Set when the route is initialised.
- * @property {String} collectionName The DB collection name
- * @property {Object} data The request body data
- * @property {Object} query The request query data
- * @property {String} schemaName The schema name for data validation
- * @property {Boolean} modifying Whether the request modifies data
- * @see {ApiRoute}
- */
-/**
- * Extends the existing Route definition with additional API-specific attributes
- * @memberof api
- * @typedef {Route} ApiRoute
- * @extends {Route}
- * @property {Array<string>} modifiers Defines which HTTP methods can modify data (verbs must be lower-case). This only needs do be defined for routes are non standard. By default, it is assumed that 'get' requests are non-modifying, and 'post', 'put', 'patch' and 'delete' are modifying.
- * @example
- * modifiers: ['post']
- * @property {Boolean} validate Whether the request data should be validated
- * @property {Object} permissions Definition of permissions allowed required to access each handler
- * @property {Array<string>} [permissions.post] Permissions scopes required to access this route
- * @property {Array<string>} [permissions.get] Permissions scopes required to access this route
- * @property {Array<string>} [permissions.put] Permissions scopes required to access this route
- * @property {Array<string>} [permissions.delete] Permissions scopes required to access this route
- * @example
- * {
- *    route: '/',
- *    handlers: { post: postHandler },
- *    permissions: { post: ['write:scope'] }
- *    modifiers: ['post'],
- * }
- */
-/**
- * @memberof api
- * @typedef {Object} InsertOptions
- * @property {String} schemaName Name of the schema to validate against
- * @property {String} collectionName DB collection to insert document into
- * @property {String} validate Whether the incoming data should be validated
- * @property {String} invokePostHook Whether the function should invoke the 'post' action hook on success
- */
-/**
- * @memberof api
- * @typedef {Object} FindOptions
- * @property {String} schemaName Name of the schema to validate against
- * @property {String} collectionName DB collection to insert document into
- */
-/**
- * @memberof api
- * @typedef {Object} UpdateOptions
- * @property {String} schemaName Name of the schema to validate against
- * @property {String} collectionName DB collection to insert document into
- * @property {Boolean} validate Whether the incoming data should be validated
- * @property {String} invokePostHook Whether the function should invoke the 'post' action hook on success
- * @property {Boolean} rawUpdate Whether the provided data should be considered 'raw' (i.e. not format and apply $set MongoDB keyword)
- */
-/**
- * @memberof api
- * @typedef {Object} DeleteOptions
- * @property {String} collectionName DB collection to remove document from
- * @property {String} invokePostHook Whether the function should invoke the 'post' action hook on success
+/**
+ * This file exists to define the below types for documentation purposes.
+ */
+/**
+ * For AbstractApiModule subclasses the Express ClientRequest object is given an extra apiData property which contains useful data related to the incoming request.
+ * Extends Route definition with additional API-specific attributes
+ * @memberof api
+ * @typedef {Object} ApiRequestData
+ * @property {Object} config The API route's config data. Set when the route is initialised.
+ * @property {String} collectionName The DB collection name
+ * @property {Object} data The request body data
+ * @property {Object} query The request query data
+ * @property {String} schemaName The schema name for data validation
+ * @property {Boolean} modifying Whether the request modifies data
+ * @see {ApiRoute}
+ */
+/**
+ * Extends the existing Route definition with additional API-specific attributes
+ * @memberof api
+ * @typedef {Route} ApiRoute
+ * @extends {Route}
+ * @property {Array<string>} modifiers Defines which HTTP methods can modify data (verbs must be lower-case). This only needs do be defined for routes are non standard. By default, it is assumed that 'get' requests are non-modifying, and 'post', 'put', 'patch' and 'delete' are modifying.
+ * @example
+ * modifiers: ['post']
+ * @property {Boolean} validate Whether the request data should be validated
+ * @property {Object} permissions Definition of permissions allowed required to access each handler
+ * @property {Array<string>} [permissions.post] Permissions scopes required to access this route
+ * @property {Array<string>} [permissions.get] Permissions scopes required to access this route
+ * @property {Array<string>} [permissions.put] Permissions scopes required to access this route
+ * @property {Array<string>} [permissions.delete] Permissions scopes required to access this route
+ * @example
+ * {
+ *    route: '/',
+ *    handlers: { post: postHandler },
+ *    permissions: { post: ['write:scope'] }
+ *    modifiers: ['post'],
+ * }
+ */
+/**
+ * @memberof api
+ * @typedef {Object} InsertOptions
+ * @property {String} schemaName Name of the schema to validate against
+ * @property {String} collectionName DB collection to insert document into
+ * @property {String} validate Whether the incoming data should be validated
+ * @property {String} invokePostHook Whether the function should invoke the 'post' action hook on success
+ */
+/**
+ * @memberof api
+ * @typedef {Object} FindOptions
+ * @property {String} schemaName Name of the schema to validate against
+ * @property {String} collectionName DB collection to insert document into
+ */
+/**
+ * @memberof api
+ * @typedef {Object} UpdateOptions
+ * @property {String} schemaName Name of the schema to validate against
+ * @property {String} collectionName DB collection to insert document into
+ * @property {Boolean} validate Whether the incoming data should be validated
+ * @property {String} invokePostHook Whether the function should invoke the 'post' action hook on success
+ * @property {Boolean} rawUpdate Whether the provided data should be considered 'raw' (i.e. not format and apply $set MongoDB keyword)
+ */
+/**
+ * @memberof api
+ * @typedef {Object} DeleteOptions
+ * @property {String} collectionName DB collection to remove document from
+ * @property {String} invokePostHook Whether the function should invoke the 'post' action hook on success
  */

package/package.json

@@ -1,23 +1,58 @@
-{
-  "name": "adapt-authoring-api",
-  "version": "0.0.1",
-  "description": "Abstract module for creating APIs",
-  "homepage": "https://github.com/adapt-security/adapt-authoring-api",
-  "license": "GPL-3.0",
-  "type": "module",
-  "main": "index.js",
-  "repository": "github:adapt-security/adapt-authoring-api",
-  "dependencies": {
-    "lodash": "^4.17.21"
-  },
-  "peerDependencies": {
-    "adapt-authoring-auth": "github:adapt-security/adapt-authoring-auth",
-    "adapt-authoring-core": "github:adapt-security/adapt-authoring-core",
-    "adapt-authoring-jsonschema": "github:adapt-security/adapt-authoring-jsonschema",
-    "adapt-authoring-mongodb": "github:adapt-security/adapt-authoring-mongodb"
-  },
-  "devDependencies": {
-    "eslint": "^9.14.0",
-    "standard": "^17.1.0"
-  }
-}
+{
+  "name": "adapt-authoring-api",
+  "version": "1.0.0",
+  "description": "Abstract module for creating APIs",
+  "homepage": "https://github.com/adapt-security/adapt-authoring-api",
+  "license": "GPL-3.0",
+  "type": "module",
+  "main": "index.js",
+  "repository": "github:adapt-security/adapt-authoring-api",
+  "dependencies": {
+    "lodash": "^4.17.21"
+  },
+  "peerDependencies": {
+    "adapt-authoring-auth": "github:adapt-security/adapt-authoring-auth",
+    "adapt-authoring-core": "github:adapt-security/adapt-authoring-core",
+    "adapt-authoring-jsonschema": "github:adapt-security/adapt-authoring-jsonschema",
+    "adapt-authoring-mongodb": "github:adapt-security/adapt-authoring-mongodb"
+  },
+  "devDependencies": {
+    "eslint": "^9.14.0",
+    "standard": "^17.1.0",
+    "@semantic-release/commit-analyzer": "^9.0.2",
+    "@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"
+  },
+  "release": {
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "preset": "eslint"
+        }
+      ],
+      [
+        "@semantic-release/release-notes-generator",
+        {
+          "preset": "eslint"
+        }
+      ],
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "package.json"
+          ],
+          "message": "Chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+        }
+      ]
+    ]
+  }
+}