@radio-garden/ditojs-server 2.85.2-0.5067ad799

package/src/schema/relations.js

@@ -0,0 +1,324 @@
+import {
+  Relation,
+  BelongsToOneRelation,
+  HasOneRelation,
+  HasOneThroughRelation,
+  HasManyRelation,
+  ManyToManyRelation
+} from 'objection'
+import {
+  isObject,
+  isArray,
+  isString,
+  isFunction,
+  asArray,
+  capitalize,
+  camelize
+} from '@ditojs/utils'
+import { RelationError } from '../errors/index.js'
+
+const relationLookup = {
+  // one:
+  belongsTo: BelongsToOneRelation,
+  hasOne: HasOneRelation,
+  hasOneThrough: HasOneThroughRelation,
+  // many:
+  hasMany: HasManyRelation,
+  manyToMany: ManyToManyRelation
+}
+
+const relationClasses = {
+  BelongsToOneRelation,
+  HasOneRelation,
+  HasOneThroughRelation,
+  HasManyRelation,
+  ManyToManyRelation
+}
+
+const throughRelationClasses = {
+  ManyToManyRelation,
+  HasOneThroughRelation
+}
+
+class ModelReference {
+  constructor(reference, models, allowUnknown = false) {
+    this.modelName = null
+    this.modelClass = null
+    this.propertyNames = []
+    // Parse and validate model key references
+    for (const ref of asArray(reference)) {
+      const [modelName, propertyName] = ref?.split('.') || []
+      const modelClass = models[modelName]
+      if (!modelClass && !allowUnknown) {
+        throw new RelationError(
+          `Unknown model reference: ${ref}`
+        )
+      }
+      if (!this.modelName) {
+        this.modelName = modelName
+        this.modelClass = modelClass
+      } else if (this.modelName !== modelName) {
+        throw new RelationError(
+          `Composite keys need to be defined on the same table: ${ref}`
+        )
+      }
+      this.propertyNames.push(propertyName)
+    }
+  }
+
+  asValue(properties) {
+    // Unpack the reference array if it doesn't contain multiple properties.
+    return properties.length > 1 ? properties : properties[0]
+  }
+
+  toValue() {
+    return this.asValue(
+      this.propertyNames.map(
+        propName => `${this.modelName}.${propName}`
+      )
+    )
+  }
+
+  toString() {
+    const value = this.toValue()
+    return isArray(value) ? `[${value.join(', ')}]` : value
+  }
+
+  buildThrough(toRef, inverse) {
+    // Auto-generate the `through` setting based on simple conventions:
+    // - The camelized through table is called: `${fromName}${toName}`
+    // - The `through.from` property is called:
+    //   `${fromModelName)${capitalize(fromProp)}`
+    // - The `through.to` property is called:
+    //   `${toModelName)${capitalize(toProp)}`
+    // NOTE: Due to the use of knexSnakeCaseMappers(), there is no need to
+    // generate actual table-names here.
+    const fromName = this.modelName
+    const fromProperties = this.propertyNames
+    const toName = toRef.modelName
+    const toProperties = toRef.propertyNames
+    if (fromProperties.length !== toProperties.length) {
+      throw new RelationError(
+        'Unable to create through join for ' +
+        `composite keys from '${this}' to '${toRef}'`
+      )
+    }
+    const from = []
+    const to = []
+    for (let i = 0; i < fromProperties.length; i++) {
+      const fromProperty = fromProperties[i]
+      const toProperty = toProperties[i]
+      if (fromProperty && toProperty) {
+        const throughName = `${fromName}${toName}`
+        const throughFrom = this.getThroughProperty(fromName, fromProperty)
+        const throughTo = this.getThroughProperty(toName, toProperty)
+        from.push(`${throughName}.${throughFrom}`)
+        to.push(`${throughName}.${throughTo}`)
+      } else {
+        throw new RelationError(
+          `Unable to create through join from '${this}' to '${to}'`
+        )
+      }
+    }
+    return {
+      from: this.asValue(inverse ? to : from),
+      to: this.asValue(inverse ? from : to)
+    }
+  }
+
+  getThroughProperty(name, property) {
+    return `${name[0].toLowerCase()}${name.slice(1)}${capitalize(property)}`
+  }
+}
+
+export function getRelationClass(relation) {
+  return isString(relation)
+    ? relationLookup[camelize(relation)] || relationClasses[relation]
+    : Relation.isPrototypeOf(relation)
+      ? relation
+      : null
+}
+
+export function isThroughRelationClass(relationClass) {
+  return throughRelationClasses[relationClass.name]
+}
+
+export function convertRelation(schema, models) {
+  let {
+    relation,
+    // Dito.js-style relation description:
+    modelClass,
+    from,
+    to,
+    through,
+    inverse,
+    modify,
+    scope,
+    filter,
+    // Objection.js-style relation description (`modify` is shared)
+    join,
+    // Pluck Dito.js-related properties that should not end up in `rest`:
+    nullable,
+    owner,
+    ...rest
+  } = schema || {}
+  const relationClass = getRelationClass(relation)
+  if (!relationClass) {
+    throw new RelationError(`Unrecognized relation: ${relation}`)
+  } else if (join && !isString(relation)) {
+    // Original Objection.js-style relation, just pass through
+    return schema
+  } else {
+    // Dito.js-style relation, e.g.:
+    // {
+    //   relation: 'hasMany',
+    //   from: 'FromModel.primaryKeyPropertyName',
+    //   to: 'ToModel.foreignKeyPropertyName',
+    //   scope: 'latest'
+    // }
+    from = new ModelReference(from, models, false)
+    to = new ModelReference(to, models, false)
+    if (isThroughRelationClass(relationClass)) {
+      if (!through) {
+        // Auto-generate the through settings, see buildThrough():
+        through = inverse
+          ? to.buildThrough(from, true)
+          : from.buildThrough(to, false)
+      } else if (through.from && through.to) {
+        // `through.from` and `through.to` need special processing, where they
+        // can either be model references or table references, and if they
+        // reference models, they should be converted to table references and
+        // the model should be extracted automatically.
+        const throughFrom = new ModelReference(through.from, models, true)
+        const throughTo = new ModelReference(through.to, models, true)
+        if (throughFrom.modelClass || throughTo.modelClass) {
+          if (throughFrom.modelClass === throughTo.modelClass) {
+            through.modelClass = throughTo.modelClass
+            through.from = throughFrom.toValue()
+            through.to = throughTo.toValue()
+          } else {
+            throw new RelationError(
+              'Both sides of the `through` definition ' +
+              'need to be on the same join model'
+            )
+          }
+        } else {
+          // Assume the references are to a join table, and use the settings
+          // unmodified.
+        }
+      } else {
+        throw new RelationError(
+          'The relation needs a `through.from` and ' + '`through.to` definition'
+        )
+      }
+    } else if (through) {
+      throw new RelationError('Unsupported through join definition')
+    }
+    // Combine `modify` and `filter` when `filter` is a function (Objection.js
+    // backward-compatible style). Otherwise, handle `filter` as a Dito.js-style
+    // filter name/array below.
+    if (isFunction(filter)) {
+      modify ||= filter
+      filter = null
+    }
+    if (isObject(modify)) {
+      // Convert a find-filter object to a filter function, same as in the
+      // handling of definition.scopes, see Model.js
+      modify = query => query.find(modify)
+    }
+    if (scope) {
+      // Create a new modify function that merges scope and modify:
+      const origModify = modify
+      modify = query => {
+        query.applyScope(
+          ...asArray(scope),
+          // Pass `false` for `checkAllowedScopes`, to always allow scopes
+          // that are defined on relations to be applied.
+          false
+        )
+        if (origModify) {
+          query.modify(origModify)
+        }
+      }
+    }
+    if (filter) {
+      // Create a new modify function that merges filter and modify:
+      const origModify = modify
+      modify = query => {
+        query.applyFilter(filter)
+        if (origModify) {
+          query.modify(origModify)
+        }
+      }
+    }
+    if (isString(modelClass)) {
+      const modelName = modelClass
+      modelClass = models[modelName]
+      if (!modelClass) {
+        throw new RelationError(
+          `Unknown model class: ${modelName}`
+        )
+      }
+    }
+    return {
+      relation: relationClass,
+      modelClass: modelClass ?? to.modelClass,
+      join: {
+        from: from.toValue(),
+        to: to.toValue(),
+        ...(through && { through })
+      },
+      ...(modify && { modify }),
+      ...rest
+    }
+  }
+}
+
+export function convertRelations(ownerModelClass, relations, models) {
+  const converted = {}
+  for (const [name, relation] of Object.entries(relations)) {
+    try {
+      converted[name] = convertRelation(relation, models)
+    } catch (err) {
+      throw new RelationError(
+        `${ownerModelClass.name}.relations.${name}: ${err.message || err}`
+      )
+    }
+  }
+  return converted
+}
+
+/**
+ * Adds JSON schema properties for each of the modelClass' relations.
+ */
+export function addRelationSchemas(modelClass, properties) {
+  for (const relationInstance of Object.values(modelClass.getRelations())) {
+    const { name, ownerModelClass, relatedModelClass } = relationInstance
+    const relationDefinition = ownerModelClass.definition.relations[name]
+    const isOneToOne = relationInstance.isOneToOne()
+    const { owner } = relationDefinition
+    const $ref = relatedModelClass.name
+    const anyOf = []
+    if (isOneToOne) {
+      // Allow null-value on one-to-one relations
+      anyOf.push({ type: 'null' })
+    }
+    if (!owner) {
+      // Allow reference objects for relations that don't own their data.
+      anyOf.push({ relate: $ref })
+    }
+    // Finally the model itself
+    anyOf.push({ $ref })
+    const items =
+      anyOf.length > 1
+        ? { anyOf }
+        : anyOf[0]
+    properties[name] = isOneToOne
+      ? items
+      : {
+          type: 'array',
+          items
+        }
+  }
+  return properties
+}

package/src/schema/relations.test.js

@@ -0,0 +1,177 @@
+import {
+  BelongsToOneRelation,
+  HasOneRelation,
+  HasOneThroughRelation,
+  HasManyRelation,
+  ManyToManyRelation
+} from 'objection'
+import { Model } from '../models/index.js'
+import {
+  getRelationClass,
+  convertRelation,
+  addRelationSchemas
+} from './relations.js'
+
+describe('getRelationClass()', () => {
+  it('returns the corresponding relation classes', () => {
+    expect(getRelationClass('belongs-to')).toBe(BelongsToOneRelation)
+    expect(getRelationClass('has-one')).toBe(HasOneRelation)
+    expect(getRelationClass('has-one-through')).toBe(HasOneThroughRelation)
+    expect(getRelationClass('has-many')).toBe(HasManyRelation)
+    expect(getRelationClass('many-to-many')).toBe(ManyToManyRelation)
+
+    expect(getRelationClass('belongsTo')).toBe(BelongsToOneRelation)
+    expect(getRelationClass('hasOne')).toBe(HasOneRelation)
+    expect(getRelationClass('hasOneThrough')).toBe(HasOneThroughRelation)
+    expect(getRelationClass('hasMany')).toBe(HasManyRelation)
+    expect(getRelationClass('manyToMany')).toBe(ManyToManyRelation)
+
+    expect(getRelationClass('BelongsToOneRelation')).toBe(BelongsToOneRelation)
+    expect(getRelationClass('HasOneRelation')).toBe(HasOneRelation)
+    expect(getRelationClass('HasOneThroughRelation'))
+      .toBe(HasOneThroughRelation)
+    expect(getRelationClass('HasManyRelation')).toBe(HasManyRelation)
+    expect(getRelationClass('ManyToManyRelation')).toBe(ManyToManyRelation)
+  })
+})
+
+describe('convertRelation()', () => {
+  class ModelOne extends Model {}
+  class ModelTwo extends Model {}
+
+  const models = { ModelOne, ModelTwo }
+
+  it('converts a belongs-to relation to Objection.js format', () => {
+    expect(
+      convertRelation(
+        {
+          relation: 'belongs-to',
+          from: 'ModelOne.modelTwoId',
+          to: 'ModelTwo.id',
+          modify: 'myScope'
+        },
+        models
+      )
+    ).toEqual({
+      relation: BelongsToOneRelation,
+      modelClass: ModelTwo,
+      join: {
+        from: 'ModelOne.modelTwoId',
+        to: 'ModelTwo.id'
+      },
+      modify: 'myScope'
+    })
+  })
+
+  it('converts a many-to-many relation to Objection.js format', () => {
+    expect(
+      convertRelation(
+        {
+          relation: 'many-to-many',
+          from: 'ModelOne.id',
+          to: 'ModelTwo.id',
+          inverse: false
+        },
+        models
+      )
+    ).toEqual({
+      relation: ManyToManyRelation,
+      modelClass: ModelTwo,
+      join: {
+        from: 'ModelOne.id',
+        through: {
+          from: 'ModelOneModelTwo.modelOneId',
+          to: 'ModelOneModelTwo.modelTwoId'
+        },
+        to: 'ModelTwo.id'
+      }
+    })
+  })
+
+  it('converts an inverse many-to-many relation to Objection.js format', () => {
+    expect(
+      convertRelation(
+        {
+          relation: 'many-to-many',
+          from: 'ModelTwo.id',
+          to: 'ModelOne.id',
+          inverse: true
+        },
+        models
+      )
+    ).toEqual({
+      relation: ManyToManyRelation,
+      modelClass: ModelOne,
+      join: {
+        from: 'ModelTwo.id',
+        through: {
+          from: 'ModelOneModelTwo.modelTwoId',
+          to: 'ModelOneModelTwo.modelOneId'
+        },
+        to: 'ModelOne.id'
+      }
+    })
+  })
+
+  it('preserves Objection.js relation format', () => {
+    const relation = {
+      relation: BelongsToOneRelation,
+      modelClass: ModelTwo,
+      join: {
+        from: 'ModelOne.modelTwoId',
+        to: 'ModelTwo.id'
+      },
+      modify: 'myScope'
+    }
+    expect(convertRelation(relation, models)).toEqual(relation)
+  })
+})
+
+describe('addRelationSchemas()', () => {
+  class ModelOne extends Model {
+    static relations = {
+      modelTwo: {
+        relation: 'belongs-to',
+        from: 'ModelOne.modelTwoId',
+        to: 'ModelTwo.id'
+      }
+    }
+  }
+
+  class ModelTwo extends Model {
+    static relations = {
+      modelOnes: {
+        relation: 'has-many',
+        from: 'ModelTwo.id',
+        to: 'ModelOne.modelTwoId',
+        owner: true
+      }
+    }
+  }
+
+  // Add a mock app to both, to expose models:
+  ModelOne.app = ModelTwo.app = {
+    models: { ModelOne, ModelTwo }
+  }
+
+  it('adds correct property schema for a belongs-to relation', () => {
+    expect(addRelationSchemas(ModelOne, {})).toEqual({
+      modelTwo: {
+        anyOf: [
+          { type: 'null' },
+          { relate: 'ModelTwo' },
+          { $ref: 'ModelTwo' }
+        ]
+      }
+    })
+  })
+
+  it('adds correct property schema for a has-many owner relation', () => {
+    expect(addRelationSchemas(ModelTwo, {})).toEqual({
+      modelOnes: {
+        type: 'array',
+        items: { $ref: 'ModelOne' }
+      }
+    })
+  })
+})