Moved @tryghost/api-framework into the Ghost monorepo

ghost/api-framework/.oxfmtrc.json

@@ -0,0 +1,13 @@
+{
+    "singleQuote": true,
+    "ignorePatterns": [
+        "**/node_modules/**",
+        "**/build/**",
+        "**/coverage/**",
+        "**/cjs/**",
+        "**/es/**",
+        "**/types/**",
+        "**/*.hbs",
+        "**/test/fixtures/**"
+    ]
+}

ghost/api-framework/.oxlintrc.json

@@ -0,0 +1,12 @@
+{
+    "plugins": ["node", "typescript"],
+    "ignorePatterns": [
+        "**/node_modules/**",
+        "**/build/**",
+        "**/coverage/**",
+        "**/cjs/**",
+        "**/es/**",
+        "**/types/**",
+        "**/test/fixtures/**"
+    ]
+}

ghost/api-framework/README.md

@@ -0,0 +1,150 @@
+# API Framework
+
+API framework used by Ghost
+
+## Purpose
+
+Composable framework for Ghost API controllers, request framing, validation/serialization pipelines, and HTTP response helpers.
+
+## Usage
+
+### Stages
+
+Each request goes through the following stages:
+
+- input validation
+- input serialisation
+- permissions
+- query
+- output serialisation
+
+The framework we are building pipes a request through these stages in respect of the API controller configuration.
+
+### Frame
+
+Is a class, which holds all the information for request processing. We pass this instance by reference.
+Each function can modify the original instance. No need to return the class instance.
+
+#### Structure
+
+```
+{
+  original: Object,
+  options: Object,
+  data: Object,
+  user: Object,
+  file: Object,
+  files: Array
+}
+```
+
+#### Example
+
+```
+{
+  original: {
+    include: 'tags'
+  },
+  options: {
+    withRelated: ['tags']
+  },
+  data: {
+    posts: []
+  }
+}
+```
+
+### API Controller
+
+A controller is no longer just a function, it's a set of configurations.
+
+#### Structure
+
+```
+edit: function || object
+```
+
+```
+edit: {
+  headers: object,
+  options: Array,
+  data: Array,
+  validation: object | function,
+  permissions: boolean | object | function,
+  query: function
+}
+```
+
+#### Examples
+
+```
+edit: {
+  headers: {
+    cacheInvalidate: true
+  },
+  // Allowed url/query params
+  options: ['include']
+  // Url/query param validation configuration
+  validation: {
+    options: {
+      include: {
+        required: true,
+        values: ['tags']
+      }
+    }
+  },
+  permissions: true,
+  // Returns a model response!
+  query(frame) {
+    return models.Post.edit(frame.data, frame.options);
+  }
+}
+```
+
+```
+read: {
+  // Allowed url/query params, which will be remembered inside `frame.data`
+  // This is helpful for READ requests e.g. `model.findOne(frame.data, frame.options)`.
+  // Our model layer requires sending the where clauses as first parameter.
+  data: ['slug']
+  validation: {
+    data: {
+      slug: {
+        values: ['eins']
+      }
+    }
+  },
+  permissions: true,
+  query(frame) {
+    return models.Post.findOne(frame.data, frame.options);
+  }
+}
+```
+
+```
+edit: {
+  validation() {
+    // custom validation, skip framework
+  },
+  permissions: {
+    unsafeAttrs: ['author']
+  },
+  query(frame) {
+    return models.Post.edit(frame.data, frame.options);
+  }
+}
+```
+
+## Develop
+
+This is a monorepo package.
+
+Follow the instructions for the top-level repo.
+
+1. `git clone` this repo & `cd` into it as usual
+2. Run `pnpm install` to install top-level dependencies.
+
+## Test
+
+- `pnpm lint` runs oxlint
+- `pnpm test` runs lint and tests

ghost/api-framework/index.js

@@ -0,0 +1,27 @@
+/** @typedef {object} PermissionsObject */
+/** @typedef {boolean} PermissionsBoolean */
+
+/** @typedef {number} StatusCodeNumber */
+/** @typedef {(result: any) => number} StatusCodeFunction */
+
+/** @typedef {object} ValidationObject */
+
+/**
+ * @typedef {object} ControllerMethod
+ * @property {object} headers
+ * @property {PermissionsBoolean | PermissionsObject} permissions
+ * @property {string[]} [options]
+ * @property {ValidationObject} [validation]
+ * @property {string[]} [data]
+ * @property {StatusCodeFunction | StatusCodeNumber} [statusCode]
+ * @property {object} [response]
+ * @property {function} [cache]
+ * @property {(frame: import('./lib/Frame')) => object} [generateCacheKeyData]
+ * @property {(frame: import('./lib/Frame')) => any} query
+ */
+
+/**
+ * @typedef {Record<string, ControllerMethod | string> & Record<'docName', string>} Controller
+ */
+
+module.exports = require('./lib/api-framework');

ghost/api-framework/lib/Frame.js

@@ -0,0 +1,110 @@
+const debug = require('@tryghost/debug')('frame');
+const _ = require('lodash');
+
+/**
+ * @description The "frame" holds all information of a request.
+ *
+ * Each party can modify the frame by reference.
+ * A request hits a lot of stages in the API implementation and that's why modification by reference was the
+ * easiest to use. We always have access to the original input, we never loose track of it.
+ */
+class Frame {
+    #headers = {};
+    constructor(obj = {}) {
+        this.original = obj;
+
+        /**
+         * options:     Query params, url params, context and custom options
+         * data:        Body or if the ctrl wants query/url params inside body
+         * user:        Logged in user
+         * file:        Uploaded file
+         * files:       Uploaded files
+         * apiType:     Content or admin api access
+         * docName:     The endpoint name, e.g. "posts"
+         * method:      The method name, e.g. "browse"
+         */
+        this.options = {};
+        this.data = {};
+        this.user = {};
+        this.file = {};
+        this.files = [];
+        this.#headers = {};
+        this.apiType = null;
+        this.docName = null;
+        this.method = null;
+        this.response = null;
+    }
+
+    /**
+     * @description Configure the frame.
+     *
+     * If you instantiate a new frame, all the data you pass in, land in `this.original`. This is helpful
+     * for debugging to see what the original input was.
+     *
+     * This function will prepare the incoming data for further processing.
+     * Based on the API ctrl implemented, this fn will pick allowed properties to either options or data.
+     */
+    configure(apiConfig) {
+        debug('configure');
+
+        if (apiConfig.options) {
+            if (typeof apiConfig.options === 'function') {
+                apiConfig.options = apiConfig.options(this);
+            }
+
+            if (Object.prototype.hasOwnProperty.call(this.original, 'query')) {
+                Object.assign(this.options, _.pick(this.original.query, apiConfig.options));
+            }
+
+            if (Object.prototype.hasOwnProperty.call(this.original, 'params')) {
+                Object.assign(this.options, _.pick(this.original.params, apiConfig.options));
+            }
+
+            if (Object.prototype.hasOwnProperty.call(this.original, 'options')) {
+                Object.assign(this.options, _.pick(this.original.options, apiConfig.options));
+            }
+        }
+
+        this.options.context = this.original.context;
+
+        if (this.original.body && Object.keys(this.original.body).length) {
+            this.data = _.cloneDeep(this.original.body);
+        } else {
+            if (apiConfig.data) {
+                if (typeof apiConfig.data === 'function') {
+                    apiConfig.data = apiConfig.data(this);
+                }
+
+                if (Object.prototype.hasOwnProperty.call(this.original, 'query')) {
+                    Object.assign(this.data, _.pick(this.original.query, apiConfig.data));
+                }
+
+                if (Object.prototype.hasOwnProperty.call(this.original, 'params')) {
+                    Object.assign(this.data, _.pick(this.original.params, apiConfig.data));
+                }
+
+                if (Object.prototype.hasOwnProperty.call(this.original, 'options')) {
+                    Object.assign(this.data, _.pick(this.original.options, apiConfig.data));
+                }
+            }
+        }
+
+        this.user = this.original.user;
+        this.file = this.original.file;
+        this.files = this.original.files;
+
+        debug('original', this.original);
+        debug('options', this.options);
+        debug('data', this.data);
+    }
+
+    setHeader(header, value) {
+        this.#headers[header] = value;
+    }
+
+    getHeaders() {
+        return Object.assign({}, this.#headers);
+    }
+}
+
+module.exports = Frame;

ghost/api-framework/lib/api-framework.js

@@ -0,0 +1,29 @@
+module.exports = {
+    get headers() {
+        return require('./headers');
+    },
+
+    get http() {
+        return require('./http');
+    },
+
+    get Frame() {
+        return require('./Frame');
+    },
+
+    get pipeline() {
+        return require('./pipeline');
+    },
+
+    get validators() {
+        return require('./validators');
+    },
+
+    get serializers() {
+        return require('./serializers');
+    },
+
+    get utils() {
+        return require('./utils');
+    },
+};