@ditojs/server 2.48.0 → 2.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ditojs/server",
-  "version": "2.48.0",
+  "version": "2.49.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",
@@ -25,10 +25,10 @@
     "node >= 18"
   ],
   "dependencies": {
-    "@ditojs/admin": "^2.48.0",
-    "@ditojs/build": "^2.48.0",
-    "@ditojs/router": "^2.48.0",
-    "@ditojs/utils": "^2.48.0",
+    "@ditojs/admin": "^2.49.0",
+    "@ditojs/build": "^2.49.0",
+    "@ditojs/router": "^2.49.0",
+    "@ditojs/utils": "^2.49.0",
     "@koa/cors": "^5.0.0",
     "@koa/multer": "^3.1.0",
     "@originjs/vite-plugin-commonjs": "^1.0.3",
@@ -66,7 +66,7 @@
     "pino-pretty": "^13.0.0",
     "pluralize": "^8.0.0",
     "repl": "^0.1.3",
-    "type-fest": "^4.40.1",
+    "type-fest": "^4.41.0",
     "uuid": "^11.1.0"
   },
   "peerDependencies": {
@@ -84,11 +84,11 @@
     "@types/koa-session": "^6.4.5",
     "@types/koa-static": "^4.0.4",
     "@types/koa__cors": "^5.0.0",
-    "@types/node": "^22.15.3",
+    "@types/node": "^22.15.17",
     "knex": "^3.1.0",
     "objection": "^3.1.5",
     "typescript": "^5.8.3"
   },
   "types": "types",
-  "gitHead": "bacff1f9a6b314fad4f01b4a83d5cf4778d344e1"
+  "gitHead": "8276ff1db64a82c03e1569e2403f378b0201ea3c"
 }

package/src/app/Validator.js

@@ -3,10 +3,15 @@ import Ajv from 'ajv/dist/2020.js'
 import addFormats from 'ajv-formats'
 import { isArray, isObject, clone, isAsync, isPromise } from '@ditojs/utils'
 import { formatJson } from '../utils/json.js'
-import * as schema from '../schema/index.js'
+import {
+  keywords as defaultKeywords,
+  formats as defaultFormats,
+  types as defaultTypes,
+  convertSchema
+} from '../schema/index.js'
 
-// Dito does not rely on objection.AjvValidator but instead implements its own
-// validator instance that is shared across the whole app and handles schema
+// Dito.js does not rely on objection.AjvValidator but instead implements its
+// own validator instance that is shared across the whole app and handles schema
 // compilation and caching differently:
 // It relies on Ajv's addSchema() / getSchema() pattern in conjunction with the
 // `schemaId: '$id'` option, and each schema is assigned an $id based on the
@@ -14,23 +19,25 @@ import * as schema from '../schema/index.js'
 // easily validate nested structures.
 
 export class Validator extends objection.Validator {
-  constructor({ options, keywords, formats } = {}) {
+  constructor({ options, keywords, formats, types } = {}) {
     super()
 
     this.options = {
       ...defaultOptions,
       ...options
     }
-
     this.keywords = {
-      ...schema.keywords,
+      ...defaultKeywords,
       ...keywords
     }
-
     this.formats = {
-      ...schema.formats,
+      ...defaultFormats,
       ...formats
     }
+    this.types = {
+      ...defaultTypes,
+      ...types
+    }
 
     this.schemas = []
 
@@ -71,6 +78,13 @@ export class Validator extends objection.Validator {
       })
     )
 
+    addSchemas(this.types, (type, schema) => {
+      ajv.addSchema({
+        $id: type,
+        ...this.processSchema(convertSchema(schema), options)
+      })
+    })
+
     // Also add all model schemas that were already compiled so far.
     for (const schema of this.schemas) {
       ajv.addSchema(this.processSchema(schema, options))

package/src/cli/console.js

@@ -32,7 +32,7 @@ export default async function startConsole(app, config) {
   server.eval = wrapEval(server)
 
   server.defineCommand('usage', {
-    help: 'Detailed Dito Console usage information',
+    help: 'Detailed Dito.js Console usage information',
     action() {
       displayUsage(app, config, true)
       this.displayPrompt()
@@ -40,7 +40,7 @@ export default async function startConsole(app, config) {
   })
 
   server.defineCommand('models', {
-    help: 'Display available Dito models',
+    help: 'Display available Dito.js models',
     action() {
       console.info(Object.keys(app.models).join(', '))
       this.displayPrompt()
@@ -99,13 +99,13 @@ function displayUsage(app, config, details) {
   console.info(deindent`
 
     ------------------------------------------------------------
-    Dito Console
+    Dito.js Console
 
     Available references:
-     - Dito app: ${pico.cyan('app')}
+     - Dito.js app: ${pico.cyan('app')}
     ${
       modelHandleNames.length > 0
-        ? ` - Dito models: ${
+        ? ` - Dito.js models: ${
             modelHandleNames.map(m => pico.cyan(m)).join(', ')
           }`
         : ''

package/src/controllers/ControllerAction.js

@@ -300,7 +300,7 @@ export default class ControllerAction {
       if (objectType) {
         if (value && isString(value)) {
           if (!/^\{.*\}$/.test(value)) {
-            // Convert simplified Dito object notation to JSON, supporting:
+            // Convert simplified Dito.js object notation to JSON, supporting:
             // - `"key1":X, "key2":Y` (curly braces are added and parsed through
             //   `JSON.parse()`)
             // - `key1:X,key2:Y` (a simple parser is applied, splitting into
@@ -329,7 +329,7 @@ export default class ControllerAction {
           }
         }
         if (objectType !== 'object' && isObject(value)) {
-          // Convert the Pojo to the desired Dito model:
+          // Convert the Pojo to the desired Dito.js model:
           const modelClass = this.app.models[objectType]
           if (modelClass && !(value instanceof modelClass)) {
             value = modelClass.fromJson(value, modelOptions)

package/src/models/Model.js

@@ -343,7 +343,7 @@ export class Model extends objection.Model {
                 },
                 {}
               ),
-              additionalProperties: false
+              unevaluatedProperties: false
             },
             {
               type: 'object',
@@ -352,7 +352,7 @@ export class Model extends objection.Model {
                   type: 'string'
                 }
               },
-              additionalProperties: false
+              unevaluatedProperties: false
             }
           ]
         },
@@ -387,13 +387,21 @@ export class Model extends objection.Model {
     return this._getCached(
       'jsonSchema',
       () => {
-        const schema = convertSchema({
-          type: 'object',
-          properties: this.definition.properties
-        })
+        const definitions = {}
+        const schema = convertSchema(
+          {
+            type: 'object',
+            properties: this.definition.properties
+          },
+          { definitions }
+        )
         addRelationSchemas(this, schema.properties)
         // Merge in root-level schema additions
         assignDeeply(schema, this.definition.schema)
+        // Merge in definitions
+        if (Object.keys(definitions).length > 0) {
+          schema.definitions = definitions
+        }
         return {
           $id: this.name,
           ...schema
@@ -467,7 +475,17 @@ export class Model extends objection.Model {
   static getAttributes(filter) {
     const attributes = []
     const { properties } = this.definition
-    for (const [name, property] of Object.entries(properties)) {
+    const { definitions } = this.jsonSchema
+    for (let [name, property] of Object.entries(properties)) {
+      // Expand $refs so we can even find properties that uses definitions:
+      const { $ref, ...schema } = property
+      const definition = $ref && definitions?.[$ref]
+      if (definition) {
+        property = {
+          ...schema,
+          ...definition
+        }
+      }
       if (filter(property)) {
         attributes.push(name)
       }
@@ -814,8 +832,8 @@ export class Model extends objection.Model {
   // @override
   static createValidator() {
     // Use a shared validator per app, so model schema can reference each other.
-    // NOTE: The Dito Validator class creates and manages this shared Objection
-    // Validator instance for us, we just need to return it here:
+    // NOTE: The Dito.js Validator class creates and manages this shared
+    // Objection Validator instance for us, we just need to return it here:
     return this.app.validator
   }
 

package/src/schema/index.js

@@ -1,4 +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 './relations.js'

package/src/schema/keywords/_extend.js

@@ -0,0 +1,31 @@
+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/schema/keywords/_instanceof.js

@@ -14,8 +14,8 @@ export const _instanceof = {
   },
 
   validate(schema, data) {
-    // Support instanceof for basic JS types and Dito models. If `this` is the
-    // validator's ctx (see passContext), then we can access the models and
+    // Support instanceof for basic JS types and Dito.js models. If `this` is
+    // the validator's ctx (see passContext), then we can access the models and
     // check.
     const models = this?.app?.models
     for (const type of asArray(schema)) {

package/src/schema/keywords/index.js

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

package/src/schema/properties.js

@@ -1,13 +1,17 @@
-import { isObject, isArray, isString } from '@ditojs/utils'
+import { isObject, isArray, isString, equals } from '@ditojs/utils'
 
 export function convertSchema(schema, options = {}) {
   if (isArray(schema)) {
-    // Needed for allOf, anyOf, oneOf, not, items:
+    // Needed for allOf, anyOf, oneOf, not, items, see below:
     schema = schema.map(entry => convertSchema(entry, options))
   } else if (isObject(schema)) {
     // Create a shallow clone so we can modify and return:
-    schema = { ...schema }
-    const { type } = schema
+    // Also collect and propagate the definitions up to the root schema through
+    // `options.definitions`, as passed from `Model static get jsonSchema()`:
+    const { definitions, ...rest } = schema
+    mergeDefinitions(options.definitions, definitions, options)
+    schema = rest
+    const { $ref, type } = schema
     if (schema.required === true) {
       // Our 'required' is not the same as JSON Schema's: Use the 'required'
       // format instead that only validates if the required value is not empty,
@@ -44,22 +48,31 @@ export function convertSchema(schema, options = {}) {
     schema.prefixItems &&= convertSchema(schema.prefixItems, options)
     schema.items &&= convertSchema(schema.items, options)
 
-    // Handle nested allOf, anyOf, oneOf, not fields
-    for (const key of ['allOf', 'anyOf', 'oneOf', 'not']) {
+    // Handle nested allOf, anyOf, oneOf & co. fields
+    for (const key of ['allOf', 'anyOf', 'oneOf', 'not', '$extend']) {
       if (key in schema) {
         schema[key] = convertSchema(schema[key], options)
       }
     }
 
-    if (isString(type)) {
+    if (isString($ref)) {
+      // If the $ref is a nested Dito.js definition, convert it to a JSON schema
+      // reference. If it is a full URL, use it as is.
+      schema.$ref = $ref.startsWith('#')
+        ? `#/definitions/${$ref}`
+        : $ref
+    } else if (isString(type)) {
       // Convert schema property notation to JSON schema
       const jsonType = jsonTypes[type]
       if (jsonType) {
         schema.type = jsonType
-        if (hasConvertedProperties && !('additionalProperties' in schema)) {
-          // Invert the logic of `additionalProperties` so that it needs to be
+        if (
+          (hasConvertedProperties || schema.discriminator) &&
+          !('unevaluatedProperties' in schema)
+        ) {
+          // Invert the logic of `unevaluatedProperties` so that it needs to be
           // explicitly set to `true`:
-          schema.additionalProperties = false
+          schema.unevaluatedProperties = false
         }
       } else if (['date', 'datetime', 'timestamp'].includes(type)) {
         // Date properties can be submitted both as a string or a Date object.
@@ -105,7 +118,7 @@ export function convertSchema(schema, options = {}) {
   return schema
 }
 
-export function convertProperties(schemaProperties, options) {
+function convertProperties(schemaProperties, options) {
   const properties = {}
   const required = []
   for (const [key, property] of Object.entries(schemaProperties)) {
@@ -117,6 +130,32 @@ export function convertProperties(schemaProperties, options) {
   return { properties, required }
 }
 
+function mergeDefinitions(definitions, defs, options) {
+  if (definitions && defs) {
+    for (const [key, def] of Object.entries(defs)) {
+      if (!key.startsWith('#')) {
+        throw new Error(
+          `Invalid definition '${
+            key
+          }', the name of nested Dito.js definitions must start with '#': ${
+            JSON.stringify(def)
+          }`
+        )
+      }
+      const definition = definitions[key]
+      const converted = convertSchema(def, options)
+      if (definition && !equals(definition, converted)) {
+        throw new Error(
+          `Duplicate nested definition for '${key}' with different schema: ${
+            JSON.stringify(def)
+          }`
+        )
+      }
+      definitions[key] = converted
+    }
+  }
+}
+
 function addFormat(schema, newFormat) {
   // Support multiple `format` keywords through `allOf`:
   const { allOf, format, ...rest } = schema

package/src/schema/properties.test.js

@@ -30,7 +30,7 @@ describe('convertSchema()', () => {
     ).toEqual({
       type: 'object',
       properties,
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -69,7 +69,7 @@ describe('convertSchema()', () => {
     ).toEqual({
       type: 'object',
       properties,
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -90,7 +90,7 @@ describe('convertSchema()', () => {
           type: 'string'
         }
       },
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -121,7 +121,7 @@ describe('convertSchema()', () => {
           format: 'required'
         }
       },
-      additionalProperties: false,
+      unevaluatedProperties: false,
       required: ['myString', 'myNumber']
     })
   })
@@ -142,7 +142,7 @@ describe('convertSchema()', () => {
         myString: { type: 'string' },
         myNumber: { type: 'number' }
       },
-      additionalProperties: false,
+      unevaluatedProperties: false,
       required: ['myString', 'myNumber']
     })
   })
@@ -163,11 +163,11 @@ describe('convertSchema()', () => {
       properties: {
         myText: {
           type: 'object',
-          additionalProperties: false,
+          unevaluatedProperties: false,
           properties: {}
         }
       },
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -178,7 +178,7 @@ describe('convertSchema()', () => {
         properties: {
           myText: {
             type: 'object',
-            additionalProperties: true,
+            unevaluatedProperties: true,
             properties: {}
           }
         }
@@ -188,11 +188,11 @@ describe('convertSchema()', () => {
       properties: {
         myText: {
           type: 'object',
-          additionalProperties: true,
+          unevaluatedProperties: true,
           properties: {}
         }
       },
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -223,11 +223,11 @@ describe('convertSchema()', () => {
               format: 'required'
             }
           },
-          additionalProperties: false,
+          unevaluatedProperties: false,
           required: ['myProperty']
         }
       },
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -256,10 +256,10 @@ describe('convertSchema()', () => {
               type: 'string'
             }
           },
-          additionalProperties: false
+          unevaluatedProperties: false
         }
       },
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -295,7 +295,7 @@ describe('convertSchema()', () => {
           format: 'date-time'
         }
       },
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -316,7 +316,7 @@ describe('convertSchema()', () => {
           $ref: 'MyModel'
         }
       },
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -343,7 +343,7 @@ describe('convertSchema()', () => {
           instanceof: 'MyModel'
         }
       },
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -366,7 +366,7 @@ describe('convertSchema()', () => {
           nullable: true
         }
       },
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -391,7 +391,7 @@ describe('convertSchema()', () => {
           ]
         }
       },
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -415,7 +415,7 @@ describe('convertSchema()', () => {
           nullable: true
         }
       },
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -440,7 +440,7 @@ describe('convertSchema()', () => {
           nullable: true
         }
       },
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -504,7 +504,7 @@ describe('convertSchema()', () => {
                   }
                 },
                 required: ['prop1', 'prop2'],
-                additionalProperties: false
+                unevaluatedProperties: false
               },
               {
                 type: 'object',
@@ -519,13 +519,13 @@ describe('convertSchema()', () => {
                   }
                 },
                 required: ['prop3', 'prop4'],
-                additionalProperties: false
+                unevaluatedProperties: false
               }
             ]
           }
         }
       },
-      additionalProperties: false
+      unevaluatedProperties: false
     })
   })
 
@@ -566,11 +566,11 @@ describe('convertSchema()', () => {
               type: 'number'
             }
           },
-          additionalProperties: false,
+          unevaluatedProperties: false,
           required: ['prop1', 'prop2']
         }
       },
-      additionalProperties: false,
+      unevaluatedProperties: false,
       required: ['myObject']
     })
   })
@@ -605,6 +605,7 @@ describe('convertSchema()', () => {
     ).toEqual({
       type: 'object',
       discriminator: { propertyName: 'foo' },
+      unevaluatedProperties: false,
       required: ['foo'],
       oneOf: [
         {
@@ -630,4 +631,76 @@ describe('convertSchema()', () => {
       ]
     })
   })
+
+  it('supports nested Dito.js definitions', () => {
+    const definitions = {}
+    expect(
+      convertSchema(
+        {
+          type: 'object',
+          properties: {
+            prop1: {
+              $ref: '#type1'
+            },
+            prop2: {
+              type: 'object',
+              properties: {
+                prop3: {
+                  $ref: '#type2'
+                }
+              },
+              definitions: {
+                '#type2': {
+                  type: 'object',
+                  properties: {
+                    prop3: {
+                      type: 'string'
+                    }
+                  }
+                }
+              }
+            }
+          },
+
+          definitions: {
+            '#type1': {
+              type: 'integer'
+            }
+          }
+        },
+        { definitions }
+      )
+    ).toEqual({
+      type: 'object',
+      unevaluatedProperties: false,
+      properties: {
+        prop1: {
+          $ref: '#/definitions/#type1'
+        },
+        prop2: {
+          type: 'object',
+          unevaluatedProperties: false,
+          properties: {
+            prop3: {
+              $ref: '#/definitions/#type2'
+            }
+          }
+        }
+      }
+    })
+    expect(definitions).toEqual({
+      '#type1': {
+        type: 'integer'
+      },
+      '#type2': {
+        type: 'object',
+        unevaluatedProperties: false,
+        properties: {
+          prop3: {
+            type: 'string'
+          }
+        }
+      }
+    })
+  })
 })

package/src/schema/types/_asset.js

@@ -0,0 +1,31 @@
+export const asset = {
+  type: 'object',
+  properties: {
+    key: {
+      type: 'string',
+      required: true
+    },
+    name: {
+      type: 'string',
+      required: true
+    },
+    type: {
+      type: 'string',
+      required: true
+    },
+    size: {
+      type: 'integer',
+      required: true
+    },
+    url: {
+      type: 'string',
+      format: 'uri'
+    },
+    width: {
+      type: 'integer'
+    },
+    height: {
+      type: 'integer'
+    }
+  }
+}

package/src/schema/types/index.js

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

package/src/storage/AssetFile.js

@@ -60,7 +60,6 @@ export class AssetFile {
   static convert(object, storage) {
     Object.setPrototypeOf(object, AssetFile.prototype)
     setHiddenProperty(object, SYMBOL_STORAGE, storage)
-    return object
   }
 
   static create(options) {

package/src/storage/Storage.js

@@ -77,7 +77,7 @@ export class Storage {
   }
 
   convertAssetFile(file) {
-    return AssetFile.convert(file, this)
+    AssetFile.convert(file, this)
   }
 
   convertStorageFile(storageFile) {

package/types/index.d.ts

@@ -3,7 +3,7 @@
 // Type definitions for Dito.js server
 // Project: <https://github.com/ditojs/dito/>
 
-// Export the entire Dito namespace.
+// Export the entire Dito.js namespace.
 
 import { ObjectCannedACL, S3ClientConfig } from '@aws-sdk/client-s3'
 import { DateFormat } from '@ditojs/utils'
@@ -645,14 +645,15 @@ export class Model extends objection.Model {
   }
 
   /**
-   * Dito automatically adds an `id` property if a model property with the
+   * Dito.js automatically adds an `id` property if a model property with the
    * `primary: true` setting is not already explicitly defined.
    */
   readonly id: Id
 
   /**
-   * Dito automatically adds a `foreignKeyId` property if foreign keys occurring
-   * in relations definitions are not explicitly defined in the properties.
+   * Dito.js automatically adds a `foreignKeyId` property if foreign keys
+   * occurring in relations definitions are not explicitly defined in the
+   * properties.
    */
   readonly foreignKeyId: Id