@ditojs/server 0.275.0 → 1.0.0

package/src/controllers/Controller.js

@@ -1,11 +1,14 @@
 import pico from 'picocolors'
-import { getOwnProperty, getAllKeys, describeFunction } from '@/utils'
-import { EventEmitter } from '@/lib'
-import ControllerAction from './ControllerAction'
-import MemberAction from './MemberAction'
+import { EventEmitter } from '../lib/index.js'
+import ControllerAction from './ControllerAction.js'
+import MemberAction from './MemberAction.js'
 import {
   ResponseError, WrappedError, ControllerError, AuthorizationError
-} from '@/errors'
+} from '../errors/index.js'
+import {
+  getOwnProperty, getAllKeys, processHandlerParameters, describeFunction,
+  formatJson, deprecate
+} from '../utils/index.js'
 import {
   isObject, isString, isArray, isBoolean, isFunction, asArray, equals,
   parseDataPath, normalizeDataPath
@@ -73,10 +76,10 @@ export class Controller {
 
     const addAction = key => {
       const value = this[key]
-      // NOTE: Only add instance methods that have a @action() decorator,
-      // which in turn sets the `verb` property on the method, or action objects
-      // which have the `verb` property:
-      if (value?.verb) {
+      // NOTE: Only add instance methods that have a @action() decorator, which
+      // in turn sets the `method` property on the method, as well as action
+      // objects which provide the `method` property:
+      if (value?.method) {
         controller[key] = value
       }
     }
@@ -89,10 +92,10 @@ export class Controller {
     return controller
   }
 
-  setupRoute(verb, url, transacted, authorize, action, handlers) {
+  setupRoute(method, url, transacted, authorize, action, middlewares) {
     this.log(
       `${
-        pico.magenta(verb.toUpperCase())
+        pico.magenta(method.toUpperCase())
       } ${
         pico.green(this.url)
       }${
@@ -102,7 +105,7 @@ export class Controller {
       }`,
       this.level + 1
     )
-    this.app.addRoute(verb, url, transacted, handlers, this, action)
+    this.app.addRoute(method, url, transacted, middlewares, this, action)
   }
 
   setupActions(type) {
@@ -110,26 +113,25 @@ export class Controller {
       values: actions,
       authorize
     } = this.processValues(this.inheritValues(type))
-    for (const [name, handler] of Object.entries(actions)) {
-      this.setupAction(type, actions, name, handler, authorize[name])
+    for (const [name, action] of Object.entries(actions)) {
+      // Replace the action object with the converted action handler, so they
+      // too can benefit from prototypal inheritance:
+      actions[name] = this.setupAction(
+        type, actions, name, action, authorize[name]
+      )
     }
     return actions
   }
 
-  setupAction(
-    type,
-    actions,
-    name,
-    handler,
-    authorize,
-    // These values are only changed when called from
-    // `CollectionController.setupAction()`:
-    verb = 'get',
-    // The default path for actions is the normalized name.
-    path = this.app.normalizePath(name)
-  ) {
-    if (!isFunction(handler)) {
-      handler = setupHandlerFromObject(handler, actions)
+  setupAction(type, actions, name, action, authorize) {
+    const handler = isFunction(action) ? action
+      : isObject(action) ? convertActionObject(name, action, actions)
+      : null
+    // Action naming convention: `'<method> <path>'`, or just `'<method>'` for
+    // the default methods.
+    let [method, path = ''] = name.split(' ')
+    if (!isMethodAction(method)) {
+      path = name
     }
     // Custom member actions have their own class so they can fetch the members
     // ahead of their call.
@@ -137,14 +139,15 @@ export class Controller {
     this.setupActionRoute(
       type,
       // eslint-disable-next-line new-cap
-      new actionClass(this, handler, type, name, verb, path, authorize)
+      new actionClass(this, handler, type, name, method, path, authorize)
     )
+    return handler
   }
 
   setupActionRoute(type, action) {
     const url = this.getUrl(type, action.path)
-    const { verb, transacted, authorize } = action
-    this.setupRoute(verb, url, transacted, authorize, action, [
+    const { method, transacted, authorize } = action
+    this.setupRoute(method, url, transacted, authorize, action, [
       async ctx => {
         try {
           const res = await action.callAction(ctx)
@@ -232,6 +235,7 @@ export class Controller {
     ])
   }
 
+  // @return {Application|Function} [app or function]
   compose() {
     // To be overridden in sub-classes, if the controller needs to install
     // middleware. For normal routes, use `this.app.addRoute()` instead.
@@ -250,11 +254,11 @@ export class Controller {
 
   inheritValues(type) {
     // Gets the controller class's instance field for a given action type, e.g.
-    // `controller` (Controller), `collection`, `member` (ModelController,
-    // RelationController), `relation` (RelationController), and sets up an
+    // `controller` (`Controller`), `collection`, `member` (`ModelController`,
+    // `RelationController`), `relation` (`RelationController`), and sets up an
     // inheritance chain for it that goes all the way up to it base class (e.g.
-    // CollectionController), so that the default definitions for all http verbs
-    // can be correctly inherited and overridden while using `super.<action>()`.
+    // `CollectionController`), so that the default definitions for all HTTP
+    // methods can be inherited and overridden while using `super.<action>()`.
     const parentClass = Object.getPrototypeOf(this.constructor)
     // Create one instance of each controller class up the chain in order to
     // get to their definitions of the inheritable values. Cache both instance
@@ -389,7 +393,7 @@ export class Controller {
           return result
         },
         // Create a new object for the filtered `values` that keeps inheritance
-        // intact. This is required by `setupHandlerFromObject()`, to support
+        // intact. This is required by `convertActionObject()`, to support
         // `super` in handler functions.
         Object.create(Object.getPrototypeOf(values))
       ),
@@ -400,14 +404,14 @@ export class Controller {
 
   async emitHook(type, handleResult, ctx, ...args) {
     let result = handleResult ? args.shift() : undefined
-    for (const handler of this.listeners(type)) {
+    for (const listener of this.listeners(type)) {
       if (handleResult) {
-        const res = await handler.call(this, ctx, result, ...args)
+        const res = await listener.call(this, ctx, result, ...args)
         if (res !== undefined) {
           result = res
         }
       } else {
-        await handler.call(this, ctx, ...args)
+        await listener.call(this, ctx, ...args)
       }
     }
     return result
@@ -503,62 +507,53 @@ EventEmitter.mixin(Controller.prototype)
 
 const inheritanceMap = new WeakMap()
 
-function setupHandlerFromObject(object, actions) {
+function convertActionObject(name, object, actions) {
   const {
     handler,
     action,
     authorize,
+    transacted,
+    scope,
     parameters,
     returns,
-    scope,
-    transacted
+    ...rest
   } = object
 
   // In order to suport `super` calls in the `handler` function in object
   // notation, deploy this crazy JS sorcery:
   Object.setPrototypeOf(object, Object.getPrototypeOf(actions))
 
-  handler.authorize = authorize
-  handler.transacted = transacted
-
   if (action) {
-    const [verb, path] = asArray(action)
-    handler.verb = verb
+    deprecate(`action.action is deprecated. Use action.method and action.path instead.`)
+    const [method, path] = asArray(action)
+    handler.method = method
     handler.path = path
   }
 
-  if (parameters) {
-    const [_parameters, options] = parameters
-    const hasOptions = isArray(_parameters)
-    handler.parameters = hasOptions ? _parameters : parameters
-
-    // If validation options are provided, expose them through
-    // `handler.options.parameters`, see ControllerAction
-    if (hasOptions) {
-      handler.options = {
-        ...handler.options,
-        parameters: options
-      }
-    }
+  if (!handler) {
+    throw new Error(`Missing handler in '${name}' action: ${formatJson(object)}`)
   }
 
-  if (returns) {
-    const [_returns, options] = asArray(returns)
-    handler.returns = _returns
+  handler.authorize = authorize ?? null
+  handler.transacted = transacted ?? null
+  handler.scope = scope ? asArray(scope) : null
 
-    // If validation options are provided, expose them through
-    // `handler.options.returns`, see ControllerAction
-    if (options) {
-      handler.options = {
-        ...handler.options,
-        parameters: options
-      }
-    }
-  }
+  processHandlerParameters(handler, 'parameters', parameters)
+  processHandlerParameters(handler, 'returns', returns)
 
-  if (scope) {
-    handler.scope = asArray(scope)
-  }
+  return Object.assign(handler, rest)
+}
 
-  return handler
+function isMethodAction(name) {
+  return {
+    get: true,
+    delete: true,
+    post: true,
+    put: true,
+    patch: true,
+    head: true,
+    options: true,
+    trace: true,
+    connect: true
+  }[name]
 }

package/src/controllers/ControllerAction.js

@@ -1,37 +1,56 @@
 import { isString, isObject, asArray, clone } from '@ditojs/utils'
 
 export default class ControllerAction {
-  constructor(controller, handler, type, name, verb, path, authorize) {
+  constructor(controller, handler, type, name, _method, _path, _authorize) {
+    const {
+      core = false,
+      // Allow decorators on actions to override the predetermined defaults for
+      // `method`, `path` and `authorize`:
+      // TODO: `handler.method` and `handler.path` were deprecated in March
+      // 2022, remove later and only set the valued passed to constructor then.
+      method = _method,
+      path = _path,
+      scope,
+      authorize,
+      transacted,
+      parameters,
+      returns,
+      options = {},
+      ...additional
+    } = handler
+
     this.controller = controller
     this.handler = handler
     this.type = type
     this.name = name
     this.identifier = `${type}:${name}`
-    // Allow decorators on actions to override the predetermined defaults for
-    // `verb`, `path` and `authorize`:
-    this.verb = handler.verb || verb
-    // Use ?? instead of || to allow '' to override the path.
-    this.path = handler.path ?? path
-    this.authorize = handler.authorize || authorize
+    this.method = method
+    this.path = path
+    this.scope = scope
+    this.authorize = authorize || _authorize
     this.transacted = !!(
-      handler.transacted ||
-      controller.transacted ||
-      // Core graph and assets operations are always transacted, unless the verb
-      // is 'get':
-      handler.core && verb !== 'get' && (controller.graph || controller.assets)
+      transacted ||
+      controller.transacted || (
+        // Core graph and assets operations are always transacted, unless the
+        // method is 'get':
+        core && method !== 'get' && (
+          controller.graph ||
+          controller.assets
+        )
+      )
     )
     this.authorization = controller.processAuthorize(this.authorize)
     this.app = controller.app
-    this.paramsName = ['post', 'put', 'patch'].includes(this.verb)
+    this.paramsName = ['post', 'put', 'patch'].includes(this.method)
       ? 'body'
       : 'query'
-    const { parameters, returns, options = {} } = this.handler
     this.parameters = this.app.compileParametersValidator(parameters, {
       async: true,
-      ...options.parameters, // See @parameters() decorator
+      ...options.parameters,
       dataName: this.paramsName
     })
     this.returns = this.app.compileParametersValidator(
+      // TODO: Shouldn't we set `this.returns` to null instead?
       returns ? [returns] : [],
       {
         async: true,
@@ -43,12 +62,15 @@ export default class ControllerAction {
         dataName: 'returns'
       }
     )
+    // Copy over the additional properties, e.g. `cached` so application
+    // middleware can implement caching mechanisms:
+    Object.assign(this, additional)
   }
 
   // Possible values for `from` are:
   // - 'path': Use `ctx.params` which is mapped to the route / path
-  // - 'query': Use `ctx.request.query`, regardless of the action's verb.
-  // - 'body': Use `ctx.request.body`, regardless of the action's verb.
+  // - 'query': Use `ctx.request.query`, regardless of the action's method.
+  // - 'body': Use `ctx.request.body`, regardless of the action's method.
   getParams(ctx, from = this.paramsName) {
     const value = from === 'path' ? ctx.params : ctx.request[from]
     // koa-bodyparser always sets an object, even when there is no body.

package/src/controllers/MemberAction.js

@@ -1,4 +1,4 @@
-import ControllerAction from './ControllerAction'
+import ControllerAction from './ControllerAction.js'
 
 export default class MemberAction extends ControllerAction {
   // @override
@@ -9,7 +9,7 @@ export default class MemberAction extends ControllerAction {
 
   // @override
   async getMember(ctx, param) {
-    // member @parameters() can provide special query parameters as well,
+    // member parameters can provide special query parameters as well,
     // and they can even controll `forUpdate()` behavior:
     // {
     //   member: true,

package/src/controllers/ModelController.js

@@ -1,9 +1,9 @@
 import pluralize from 'pluralize'
 import { isObject, camelize } from '@ditojs/utils'
-import { ControllerError } from '@/errors'
-import { CollectionController } from './CollectionController'
-import { RelationController } from './RelationController'
-import { setupPropertyInheritance } from '@/utils'
+import { CollectionController } from './CollectionController.js'
+import { RelationController } from './RelationController.js'
+import { ControllerError } from '../errors/index.js'
+import { setupPropertyInheritance } from '../utils/index.js'
 
 export class ModelController extends CollectionController {
   setup() {

package/src/controllers/RelationController.js

@@ -1,8 +1,8 @@
 import pico from 'picocolors'
-import { ControllerError } from '@/errors'
-import { CollectionController } from './CollectionController'
-import { setupPropertyInheritance, getScope } from '@/utils'
 import { asArray } from '@ditojs/utils'
+import { CollectionController } from './CollectionController.js'
+import { ControllerError } from '../errors/index.js'
+import { setupPropertyInheritance, getScope } from '../utils/index.js'
 
 export class RelationController extends CollectionController {
   constructor(parent, object, relationInstance, relationDefinition) {

package/src/controllers/{UserController.js → UsersController.js}

@@ -1,11 +1,8 @@
-import { action } from '@/decorators'
-import { ModelController } from './ModelController'
+import { ModelController } from './ModelController.js'
 
-// TODO: Rename to UsersController?
-export class UserController extends ModelController {
+export class UsersController extends ModelController {
   collection = {
-    @action('post')
-    async login(ctx) {
+    async 'post login'(ctx) {
       let user
       let error
       try {
@@ -26,8 +23,7 @@ export class UserController extends ModelController {
       }
     },
 
-    @action('post')
-    async logout(ctx) {
+    async 'post logout'(ctx) {
       let success = false
       if (this.isAuthenticated(ctx)) {
         await ctx.logout()
@@ -39,19 +35,18 @@ export class UserController extends ModelController {
       }
     },
 
-    @action('get')
-    session(ctx) {
+    'get session'(ctx) {
       const authenticated = this.isAuthenticated(ctx)
       return {
         authenticated,
         user: authenticated ? ctx.state.user : null
+
       }
     },
 
-    @action('get')
-    self(ctx) {
+    'get self'(ctx) {
       return this.isAuthenticated(ctx)
-        ? this.member.find.call(
+        ? this.member.get.call(
           this,
           this.getContextWithMemberId(ctx, ctx.state.user.$id())
         )

package/src/controllers/index.js

@@ -1,5 +1,5 @@
-export * from './Controller'
-export * from './ModelController'
-export * from './RelationController'
-export * from './AdminController'
-export * from './UserController'
+export * from './Controller.js'
+export * from './ModelController.js'
+export * from './RelationController.js'
+export * from './AdminController.js'
+export * from './UsersController.js'

package/src/decorators/action.js

@@ -1,8 +1,8 @@
-import { createDecorator } from '@/utils'
+import { createDecorator } from '../utils/index.js'
 
-export function action(verb, path) {
+export function action(method, path) {
   return createDecorator(value => {
-    value.verb = verb
+    value.method = method
     value.path = path
   })
 }

package/src/decorators/authorize.js

@@ -1,4 +1,4 @@
-import { createDecorator } from '@/utils'
+import { createDecorator } from '../utils/index.js'
 
 export function authorize(authorize) {
   return createDecorator(value => {

package/src/decorators/index.js

@@ -1,6 +1,6 @@
-export * from './action'
-export * from './authorize'
-export * from './parameters'
-export * from './returns'
-export * from './scope'
-export * from './transacted'
+export * from './action.js'
+export * from './authorize.js'
+export * from './parameters.js'
+export * from './returns.js'
+export * from './scope.js'
+export * from './transacted.js'

package/src/decorators/parameters.js

@@ -1,5 +1,5 @@
 import { isArray, isObject } from '@ditojs/utils'
-import { createDecorator, deprecate, formatJson } from '@/utils'
+import { createDecorator, deprecate, formatJson } from '../utils/index.js'
 
 export function parameters(parameters, options) {
   if (isObject(parameters)) {

package/src/decorators/returns.js

@@ -1,5 +1,5 @@
 import { isObject } from '@ditojs/utils'
-import { createDecorator, formatJson } from '@/utils'
+import { createDecorator, formatJson } from '../utils/index.js'
 
 export function returns(returns, options) {
   if (!isObject(returns)) {

package/src/decorators/scope.js

@@ -1,4 +1,4 @@
-import { createDecorator } from '@/utils'
+import { createDecorator } from '../utils/index.js'
 
 export function scope(...scopes) {
   return createDecorator(value => {

package/src/decorators/transacted.js

@@ -1,4 +1,4 @@
-import { createDecorator } from '@/utils'
+import { createDecorator } from '../utils/index.js'
 
 export const transacted = createDecorator(value => {
   value.transacted = true

package/src/errors/AssetError.js

@@ -1,4 +1,4 @@
-import { ResponseError } from './ResponseError'
+import { ResponseError } from './ResponseError.js'
 
 export class AssetError extends ResponseError {
   constructor(error) {

package/src/errors/AuthenticationError.js

@@ -1,4 +1,4 @@
-import { ResponseError } from './ResponseError'
+import { ResponseError } from './ResponseError.js'
 
 export class AuthenticationError extends ResponseError {
   constructor(error) {

package/src/errors/AuthorizationError.js

@@ -1,4 +1,4 @@
-import { ResponseError } from './ResponseError'
+import { ResponseError } from './ResponseError.js'
 
 export class AuthorizationError extends ResponseError {
   constructor(error) {

package/src/errors/ControllerError.js

@@ -1,5 +1,5 @@
-import { ResponseError } from './ResponseError'
 import { isFunction } from '@ditojs/utils'
+import { ResponseError } from './ResponseError.js'
 
 export class ControllerError extends ResponseError {
   constructor(controller, error) {

package/src/errors/DatabaseError.js

@@ -1,11 +1,20 @@
-import { WrappedError } from './WrappedError'
-import {
+import { WrappedError } from './WrappedError.js'
+// TODO: Import directly once we can move to Objection 3 and this is fixed:
+// import {
+//   DBError,
+//   DataError,
+//   CheckViolationError,
+//   NotNullViolationError,
+//   ConstraintViolationError
+// } from 'objection'
+import objection from 'objection'
+const {
   DBError,
   DataError,
   CheckViolationError,
   NotNullViolationError,
   ConstraintViolationError
-} from 'objection'
+} = objection
 
 export class DatabaseError extends WrappedError {
   constructor(error, overrides) {

package/src/errors/GraphError.js

@@ -1,4 +1,4 @@
-import { ResponseError } from './ResponseError'
+import { ResponseError } from './ResponseError.js'
 
 export class GraphError extends ResponseError {
   constructor(error) {

package/src/errors/ModelError.js

@@ -1,5 +1,5 @@
-import { ResponseError } from './ResponseError'
 import { isFunction } from '@ditojs/utils'
+import { ResponseError } from './ResponseError.js'
 
 export class ModelError extends ResponseError {
   constructor(model, error) {

package/src/errors/NotFoundError.js

@@ -1,4 +1,4 @@
-import { ResponseError } from './ResponseError'
+import { ResponseError } from './ResponseError.js'
 
 export class NotFoundError extends ResponseError {
   constructor(error) {

package/src/errors/NotImplementedError.js

@@ -1,4 +1,4 @@
-import { ResponseError } from './ResponseError'
+import { ResponseError } from './ResponseError.js'
 
 export class NotImplementedError extends ResponseError {
   constructor(error) {

package/src/errors/QueryBuilderError.js

@@ -1,4 +1,4 @@
-import { ResponseError } from './ResponseError'
+import { ResponseError } from './ResponseError.js'
 
 export class QueryBuilderError extends ResponseError {
   constructor(error) {

package/src/errors/RelationError.js

@@ -1,4 +1,4 @@
-import { WrappedError } from './WrappedError'
+import { WrappedError } from './WrappedError.js'
 import { isObject } from '@ditojs/utils'
 
 export class RelationError extends WrappedError {

package/src/errors/ValidationError.js

@@ -1,4 +1,4 @@
-import { ResponseError } from './ResponseError'
+import { ResponseError } from './ResponseError.js'
 
 export class ValidationError extends ResponseError {
   constructor(error) {

package/src/errors/WrappedError.js

@@ -1,4 +1,4 @@
-import { ResponseError } from './ResponseError'
+import { ResponseError } from './ResponseError.js'
 
 export class WrappedError extends ResponseError {
   constructor(error, overrides, defaults = {