@ditojs/server 2.49.1 → 2.51.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@ditojs/server",
-  "version": "2.49.1",
+  "version": "2.51.0",
   "type": "module",
   "description": "Dito.js Server – Dito.js is a declarative and modern web framework, based on Objection.js, Koa.js and Vue.js",
   "repository": "https://github.com/ditojs/dito/tree/master/packages/server",
   "author": "Jürg Lehni <juerg@scratchdisk.com> (http://scratchdisk.com)",
   "license": "MIT",
   "main": "./src/index.js",
+  "types": "./types/index.d.ts",
   "files": [
     "src/",
     "types/"
@@ -25,10 +26,10 @@
     "node >= 18"
   ],
   "dependencies": {
-    "@ditojs/admin": "^2.49.1",
-    "@ditojs/build": "^2.49.1",
-    "@ditojs/router": "^2.49.0",
-    "@ditojs/utils": "^2.49.0",
+    "@ditojs/admin": "^2.51.0",
+    "@ditojs/build": "^2.51.0",
+    "@ditojs/router": "^2.51.0",
+    "@ditojs/utils": "^2.51.0",
     "@koa/cors": "^5.0.0",
     "@koa/multer": "^3.1.0",
     "@originjs/vite-plugin-commonjs": "^1.0.3",
@@ -84,11 +85,10 @@
     "@types/koa-session": "^6.4.5",
     "@types/koa-static": "^4.0.4",
     "@types/koa__cors": "^5.0.0",
-    "@types/node": "^22.15.17",
+    "@types/node": "^22.15.18",
     "knex": "^3.1.0",
     "objection": "^3.1.5",
     "typescript": "^5.8.3"
   },
-  "types": "types",
-  "gitHead": "45e0fcf6cc3616b095ad32928cba034198b01ba0"
+  "gitHead": "0b8f114647510db71c50be9fdc331297b1e726ab"
 }

package/src/app/Application.js

@@ -534,6 +534,15 @@ export class Application extends Koa {
     const schema = properties
       ? convertSchema({ type: 'object', properties }, options)
       : null
+
+    // Method to recursively check the compiled JSON schema and its sub-schemas
+    // to see if it has any `$ref` references to model schemas:
+    const hasModelRefs = schema => (
+      !!this.models[schema?.$ref] ||
+      (isArray(schema) || isPlainObject(schema)) &&
+      Object.values(schema).some(hasModelRefs)
+    )
+
     const validate = this.compileValidator(schema, {
       // For parameters, always coerce types, including arrays.
       coerceTypes: 'array',
@@ -552,7 +561,10 @@ export class Application extends Koa {
       validate: validate
         ? // Use `call()` to pass ctx as context to Ajv, see passContext:
           data => validate.call(ctx, data)
-        : null
+        : null,
+      get hasModelRefs() {
+        return hasModelRefs(schema)
+      }
     }
   }
 

package/src/controllers/Controller.js

@@ -25,7 +25,8 @@ import {
   asArray,
   equals,
   parseDataPath,
-  normalizeDataPath
+  normalizeDataPath,
+  deprecate
 } from '@ditojs/utils'
 
 export class Controller {
@@ -602,10 +603,20 @@ function convertActionObject(name, object, actions) {
     transacted,
     scope,
     parameters,
+    // TODO: `returns` was deprecated in May 2025 in favour of `response`.
+    // Remove this in 2026.
     returns,
+    response = returns,
     ...rest
   } = object
 
+  if (returns) {
+    deprecate(
+      'The `returns` property is deprecated in favour of `response`. ' +
+      'Update your handler definition to use `response` instead.'
+    )
+  }
+
   // In order to support `super` calls in the `handler` function in object
   // notation, deploy this crazy JS sorcery:
   Object.setPrototypeOf(object, Object.getPrototypeOf(actions))
@@ -621,7 +632,7 @@ function convertActionObject(name, object, actions) {
   handler.scope = scope ? asArray(scope) : null
 
   processHandlerParameters(handler, 'parameters', parameters)
-  processHandlerParameters(handler, 'returns', returns)
+  processHandlerParameters(handler, 'response', response)
 
   return Object.assign(handler, rest)
 }

package/src/controllers/ControllerAction.js

@@ -1,4 +1,11 @@
-import { isString, isObject, asArray, clone } from '@ditojs/utils'
+import {
+  isString,
+  isObject,
+  asArray,
+  clone,
+  convertToJson,
+  deprecate
+} from '@ditojs/utils'
 
 export default class ControllerAction {
   constructor(
@@ -17,11 +24,21 @@ export default class ControllerAction {
       authorize,
       transacted,
       parameters,
+      // TODO: `returns` was deprecated in May 2025 in favour of `response`.
+      // Remove this in 2026.
       returns,
+      response = returns,
       options = {},
       ...additional
     } = handler
 
+    if (returns) {
+      deprecate(
+        'The `returns` property is deprecated in favour of `response`. ' +
+        'Update your handler definition to use `response` instead.'
+      )
+    }
+
     this.app = controller.app
     this.controller = controller
     this.actions = actions
@@ -57,19 +74,17 @@ export default class ControllerAction {
       ...options.parameters,
       dataName: this.paramsName
     })
-    this.returns = this.app.compileParametersValidator(
-      // TODO: Shouldn't we set `this.returns` to null instead?
-      returns ? [returns] : [],
-      {
-        async: true,
-        // Use instanceof checks instead of $ref to check returned values.
-        // TODO: That doesn't guarantee the validity though...
-        // This should always be $ref checks, I think?
-        useInstanceOf: true,
-        ...options.returns, // See @returns() decorator
-        dataName: 'returns'
-      }
-    )
+    this.response = this.app.compileParametersValidator(asArray(response), {
+      async: true,
+      // Use patch validation for response, as we often don't return the
+      // full model with all properties, but only a subset of them.
+      patch: true,
+      // TODO: `returns` was deprecated in May 2025 in favour of `response`.
+      // Remove this in 2026.
+      ...options.returns,
+      ...options.response,
+      dataName: 'response'
+    })
     // Copy over the additional properties, e.g. `cached` so application
     // middleware can implement caching mechanisms:
     Object.assign(this, additional)
@@ -109,8 +124,14 @@ export default class ControllerAction {
     await this.controller.handleAuthorization(this.authorization, ctx, member)
     const { identifier } = this
     await this.controller.emitHook(`before:${identifier}`, false, ctx, ...args)
-    const result = await this.callHandler(ctx, ...args)
-    return this.validateResult(
+    const response = await this.callHandler(ctx, ...args)
+    const result =
+      // Don't convert response to JSON if it isn't being validated (e.g. useful
+      // for streams or buffers), or if the response contains model references.
+      !this.response.validate || this.response.hasModelRefs
+        ? response
+        : convertToJson(response)
+    return this.validateResponse(
       await this.controller.emitHook(`after:${identifier}`, true, ctx, result)
     )
   }
@@ -215,31 +236,38 @@ export default class ControllerAction {
     }
   }
 
-  async validateResult(result) {
-    if (this.returns.validate) {
-      const returnsName = this.handler.returns.name
+  async validateResponse(response) {
+    if (this.response.validate) {
+      const responseName = this.handler.response.name
+      const responseWrapped = !!responseName
       // Use dataName if no name is given, see:
-      // Application.compileParametersValidator(returns, { dataName })
-      const data = {
-        [returnsName || this.returns.dataName]: result
-      }
-
+      // Application.compileParametersValidator(response, { dataName })
+      const dataName = responseName || this.response.dataName
+      const wrapped = { [dataName]: response }
       // If a named result is defined, return the data wrapped,
       // otherwise return the original unwrapped result object.
-      const getResult = () => (returnsName ? data : result)
+      const getResult = () => (responseWrapped ? wrapped : response)
       try {
-        await this.returns.validate(data)
+        await this.response.validate(wrapped)
         return getResult()
       } catch (error) {
+        // If the error contains errors, add them to the validation error:
+        const { errors } = error
+        const regexp = new RegExp(`^/${dataName}`)
         throw this.createValidationError({
           type: 'ResultValidation',
           message: 'The returned action result is not valid',
-          errors: error.errors,
+          errors: responseWrapped
+            ? errors
+            : errors.map(error => ({
+                ...error,
+                instancePath: error.instancePath.replace(regexp, '')
+              })),
           json: getResult()
         })
       }
     }
-    return result
+    return response
   }
 
   async collectArguments(ctx, params) {

package/src/models/Model.js

@@ -6,8 +6,9 @@ import {
   isFunction,
   isPromise,
   asArray,
-  flatten,
+  clone,
   equals,
+  flatten,
   parseDataPath,
   normalizeDataPath,
   getValueAtDataPath,
@@ -181,19 +182,21 @@ export class Model extends objection.Model {
     if (options.skipValidation) {
       return json
     }
-    if (!options.graph && !options.async) {
-      // Fall back to Objection's $validate() if we don't need any of our
-      // extensions (async and graph for now):
-      return super.$validate(json, options)
-    }
     json ||= this
     const inputJson = json
-    const shallow = json.$isObjectionModel && !options.graph
+
+    const shallow = !options.graph
     if (shallow) {
-      // Strip away relations and other internal stuff.
-      json = json.$clone({ shallow: true })
+      json = clone(json, { shallow: true })
+      // Strip away relations.
+      for (const key of this.constructor.getRelationNames()) {
+        delete json[key]
+      }
       // We can mutate `json` now that we took a copy of it.
-      options = { ...options, mutable: true }
+      options = {
+        ...options,
+        mutable: true
+      }
     }
 
     const validator = this.constructor.getValidator()
@@ -209,7 +212,7 @@ export class Model extends objection.Model {
     const handleResult = result => {
       validator.afterValidate(args)
       // If `json` was shallow-cloned, copy over the possible default values.
-      return shallow ? inputJson.$set(result) : result
+      return shallow ? Object.assign(inputJson, result) : result
     }
     // Handle both async and sync validation here:
     return isPromise(result)
@@ -781,13 +784,13 @@ export class Model extends objection.Model {
       if (deprecatedPrefixes[prefix]) {
         prefix = deprecatedPrefixes[prefix]
         deprecate(
-          `The ${
+          `The '${
             modifier
-          } modifier is deprecated, use the ${
+          }' modifier is deprecated, use the '${
             prefix
           }${
             modifier.slice(1)
-          } modifier instead.`
+          }' modifier instead.`
         )
       }
 

package/src/models/definitions/filters.js

@@ -1,4 +1,4 @@
-import { isObject, isFunction } from '@ditojs/utils'
+import { isObject, isFunction, deprecate } from '@ditojs/utils'
 import { processHandlerParameters } from '../../utils/handler.js'
 import { mergeReversed } from '../../utils/object.js'
 import { QueryFilters } from '../../query/index.js'
@@ -24,9 +24,22 @@ export default function filters(values) {
 function convertFilterObject(name, object) {
   const addHandlerSettings = (handler, definition) => {
     // Copy over parameters, returns and their validation options settings.
-    const { parameters, returns, ...rest } = definition
+    const {
+      parameters,
+      // TODO: `returns` was deprecated in May 2025 in favour of `response`.
+      // Remove this in 2026.
+      returns,
+      response = returns,
+      ...rest
+    } = definition
+    if (returns) {
+      deprecate(
+        'The `returns` property is deprecated in favour of `response`. ' +
+        'Update your handler definition to use `response` instead.'
+      )
+    }
     processHandlerParameters(handler, 'parameters', parameters)
-    processHandlerParameters(handler, 'returns', returns)
+    processHandlerParameters(handler, 'response', response)
     return Object.assign(handler, rest)
   }
 
@@ -62,7 +75,7 @@ function convertFilterObject(name, object) {
 
 function wrapWithValidation(filter, name, app) {
   if (filter) {
-    // TODO: Implement `returns` validation for filters too.
+    // TODO: Implement `response` validation for filters too.
     // TODO: Share additional coercion handling with
     // `ControllerAction#coerceValue()`
     const { parameters, options = {} } = filter

package/src/schema/index.js

@@ -1,5 +1,5 @@
 export * as keywords from './keywords/index.js'
 export * as formats from './formats/index.js'
 export * as types from './types/index.js'
-export * from './properties.js'
+export * from './schema.js'
 export * from './relations.js'

package/src/schema/keywords/index.js

@@ -10,4 +10,3 @@ export * from './_instanceof.js'
 export * from './_validate.js'
 export * from './_relate.js'
 export * from './_range.js'
-export * from './_extend.js'

package/src/schema/relations.js

@@ -275,15 +275,11 @@ export function addRelationSchemas(modelClass, properties) {
     const anyOf = []
     if (isOneToOne) {
       // Allow null-value on one-to-one relations
-      anyOf.push({
-        type: 'null'
-      })
+      anyOf.push({ type: 'null' })
     }
     if (!owner) {
       // Allow reference objects for relations that don't own their data.
-      anyOf.push({
-        relate: $ref
-      })
+      anyOf.push({ relate: $ref })
     }
     // Finally the model itself
     anyOf.push({ $ref })

package/src/schema/{properties.test.js → schema.test.js}

@@ -1,4 +1,4 @@
-import { convertSchema } from './properties.js'
+import { convertSchema } from './schema.js'
 
 describe('convertSchema()', () => {
   it('expands objects with properties to full JSON schemas', () => {
@@ -147,7 +147,7 @@ describe('convertSchema()', () => {
     })
   })
 
-  it(`expands 'object' schemas with properties to JSON schemas allowing no additional properties`, () => {
+  it(`expands 'object' schemas with properties to JSON schemas allowing no unevaluated properties`, () => {
     expect(
       convertSchema({
         type: 'object',
@@ -171,7 +171,7 @@ describe('convertSchema()', () => {
     })
   })
 
-  it('preserves pre-existing settings for no additional properties', () => {
+  it('preserves pre-existing settings for no unevaluated properties', () => {
     expect(
       convertSchema({
         type: 'object',

package/src/schema/types/_color.js

@@ -0,0 +1,4 @@
+export const color = {
+  type: 'string',
+  format: 'hexcolor'
+}

package/src/schema/types/index.js

@@ -1 +1,2 @@
 export * from './_asset.js'
+export * from './_color.js'

package/types/index.d.ts

@@ -980,7 +980,7 @@ export type BaseControllerActionOptions = {
    *
    * @see {@link https://github.com/ditojs/dito/blob/master/docs/model-properties.md Model Properties}
    */
-  returns?: Schema & { name?: string }
+  response?: Schema & { name?: string }
   /**
    * The scope(s) to be applied to every query executed through the action.
    *
@@ -1778,12 +1778,12 @@ export const authorize: (
 export const parameters: (params: { [key: string]: Schema }) => Mixin
 
 /**
- * Apply the returns mixin to a controller action, in order to provide a schema
+ * Apply the response mixin to a controller action, in order to provide a schema
  * for the value returned from the action handler and optionally map the value
  * to a key inside a returned object when it contains a `name` property.
  */
-export const returns: (
-  returns: Schema & { name?: string },
+export const response: (
+  response: Schema & { name?: string },
   options: any
 ) => Mixin
 

package/src/schema/keywords/_extend.js

@@ -1,31 +0,0 @@
-import { resolve } from 'url'
-import { MissingRefError } from 'ajv'
-import { clone, mergeDeeply } from '@ditojs/utils'
-
-export const $extend = {
-  macro(schemas, parentSchema, ctx) {
-    const [source, ...patch] = schemas.map(schema => {
-      const { $ref } = schema
-      if ($ref) {
-        const { baseId, self } = ctx
-        const id =
-          baseId && baseId !== '#'
-            ? resolve(baseId, $ref)
-            : $ref
-        const validate = self.getSchema(id)
-        if (!validate) {
-          throw new MissingRefError(baseId, $ref)
-        }
-        schema = validate.schema
-      }
-      return schema
-    })
-    return mergeDeeply(clone(source), ...patch)
-  },
-
-  metaSchema: {
-    type: 'array',
-    items: { type: 'object' },
-    minItems: 2
-  }
-}

package/src/utils/decorator.js

@@ -1,10 +0,0 @@
-export function createDecorator(handler) {
-  return (target, key, descriptor) => {
-    // Convert `descriptor.initializer()` to `descriptor.value`:
-    if (descriptor.initializer) {
-      descriptor.value = descriptor.initializer()
-      delete descriptor.initializer
-    }
-    handler(descriptor.value)
-  }
-}