feat: add has many by relation (#35) (#37)

close #35

Author: kiaking

docs/guide/model/decorators.md

@@ -162,7 +162,7 @@ class User extends Model {
 Marks a property on the model as a [belongsTo attribute](../relationships/getting-started.md) type. For example:
 
 ```ts
-import { Model, BelongsTo } from '@vuex-orm/core'
+import { Model, Attr, BelongsTo } from '@vuex-orm/core'
 import User from '@/models/User'
 
 class Post extends Model {
@@ -172,7 +172,7 @@ class Post extends Model {
   userId!: number | null
 
   @BelongsTo(() => User, 'userId')
-  user: User | null
+  user!: User | null
 }
 ```
 
@@ -188,6 +188,25 @@ class User extends Model {
   static entity = 'users'
 
   @HasMany(() => Post, 'userId')
-  posts: Post[]
+  posts!: Post[]
+}
+```
+
+### `@HasManyBy`
+
+Marks a property on the model as a [hasManyBy attribute](../relationships/one-to-many) type. For example:
+
+```ts
+import { Model, HasManyBy } from '@vuex-orm/core'
+import Post from '@/models/Post'
+
+class Cluster extends Model {
+  static entity = 'clusters'
+
+  @Attr(null)
+  nodeIds!: number[]
+
+  @HasManyBy(() => Node, 'nodesId')
+  nodes!: Node[]
 }
 ```

docs/guide/relationships/one-to-many.md

@@ -88,3 +88,69 @@ class Comment extends Model {
   }
 }
 ```
+
+## One To Many By
+
+One To Many By is similar to One To Many relation but having foreign keys at parent Model as an array. For example, there could be a situation where you must parse data looks something like:
+
+```js
+{
+  nodes: {
+    1: { id: 1, name: 'Node 01' },
+    2: { id: 2, name: 'Node 02' }
+  },
+  clusters: {
+    1: {
+      id: 1,
+      name: 'Cluster 01',
+      nodeIds: [1, 2]
+    }
+  }
+}
+```
+
+As you can see, `clusters` have "Has Many" relationship with `nodes`, but `nodes` do not have foreign key set (`clusterId`). We can't use Has Many relation in this case because there is no foreign key to look for. In such cases, you may use `hasManyBy` relationship.
+
+```js
+class Node extends Model {
+  static entity = 'nodes'
+
+  static fields () {
+    return {
+      id: this.attr(null),
+      name: this.string('')
+    }
+  }
+}
+
+class Cluster extends Model {
+  static entity = 'clusters'
+
+  static fields () {
+    return {
+      id: this.attr(null),
+      nodeIds: this.attr([]),
+      name: this.string('')
+      nodes: this.hasManyBy(Node, 'nodeIds')
+    }
+  }
+}
+```
+
+Now the Cluster model is going to look for Nodes using ids at Cluster's own `nodeIds` attributes.
+
+As always, you can pass the third argument to specify which id to look for.
+
+```js
+class Cluster extends Model {
+  static entity = 'clusters'
+
+  static fields () {
+    return {
+      id: this.attr(null),
+      nodeIds: this.attr(null),
+      nodes: this.hasManyBy(Node, 'nodeIds', 'nodeId')
+    }
+  }
+}
+```

src/index.cjs.ts

@@ -24,6 +24,7 @@ import { Uid as UidAttr } from './model/attributes/types/Uid'
 import { Relation } from './model/attributes/relations/Relation'
 import { HasOne as HasOneAttr } from './model/attributes/relations/HasOne'
 import { HasMany as HasManyAttr } from './model/attributes/relations/HasMany'
+import { HasManyBy as HasManyByAttr } from './model/attributes/relations/HasManyBy'
 import { Repository } from './repository/Repository'
 import { Interpreter } from './interpreter/Interpreter'
 import { Query } from './query/Query'
@@ -54,6 +55,7 @@ export default {
   Relation,
   HasOneAttr,
   HasManyAttr,
+  HasManyByAttr,
   Repository,
   Interpreter,
   Query,

src/index.ts

@@ -14,6 +14,7 @@ export * from './model/decorators/attributes/types/Uid'
 export * from './model/decorators/attributes/relations/HasOne'
 export * from './model/decorators/attributes/relations/BelongsTo'
 export * from './model/decorators/attributes/relations/HasMany'
+export * from './model/decorators/attributes/relations/HasManyBy'
 export * from './model/decorators/Contracts'
 export * from './model/decorators/NonEnumerable'
 export * from './model/attributes/Attribute'
@@ -27,6 +28,7 @@ export * from './model/attributes/relations/Relation'
 export { HasOne as HasOneAttr } from './model/attributes/relations/HasOne'
 export { BelongsTo as BelongsToAttr } from './model/attributes/relations/BelongsTo'
 export { HasMany as HasManyAttr } from './model/attributes/relations/HasMany'
+export { HasManyBy as HasManyByAttr } from './model/attributes/relations/HasManyBy'
 export * from './modules/RootModule'
 export * from './modules/RootState'
 export * from './modules/Module'
@@ -56,6 +58,7 @@ import { Uid as UidAttr } from './model/attributes/types/Uid'
 import { Relation } from './model/attributes/relations/Relation'
 import { HasOne as HasOneAttr } from './model/attributes/relations/HasOne'
 import { HasMany as HasManyAttr } from './model/attributes/relations/HasMany'
+import { HasManyBy as HasManyByAttr } from './model/attributes/relations/HasManyBy'
 import { Repository } from './repository/Repository'
 import { Interpreter } from './interpreter/Interpreter'
 import { Query } from './query/Query'
@@ -78,6 +81,7 @@ export default {
   Relation,
   HasOneAttr,
   HasManyAttr,
+  HasManyByAttr,
   Repository,
   Interpreter,
   Query,

src/model/Model.ts

@@ -13,6 +13,7 @@ import { Relation } from './attributes/relations/Relation'
 import { HasOne } from './attributes/relations/HasOne'
 import { BelongsTo } from './attributes/relations/BelongsTo'
 import { HasMany } from './attributes/relations/HasMany'
+import { HasManyBy } from './attributes/relations/HasManyBy'
 
 export type ModelFields = Record<string, Attribute>
 export type ModelSchemas = Record<string, ModelFields>
@@ -219,6 +220,26 @@ export class Model {
     return new HasMany(model, related.newRawInstance(), foreignKey, localKey)
   }
 
+  /**
+   * Create a new HasManyBy relation instance.
+   */
+  static hasManyBy(
+    related: typeof Model,
+    foreignKey: string,
+    ownerKey?: string
+  ): HasManyBy {
+    const instance = related.newRawInstance()
+
+    ownerKey = ownerKey ?? instance.$getLocalKey()
+
+    return new HasManyBy(
+      instance,
+      related.newRawInstance(),
+      foreignKey,
+      ownerKey
+    )
+  }
+
   /**
    * Get the constructor for this model.
    */

src/model/attributes/relations/HasManyBy.ts

@@ -0,0 +1,140 @@
+import { Schema as NormalizrSchema } from 'normalizr'
+import { Schema } from '../../../schema/Schema'
+import { Element, Collection } from '../../../data/Data'
+import { Query } from '../../../query/Query'
+import { Model } from '../../Model'
+import { Relation } from './Relation'
+
+export class HasManyBy extends Relation {
+  /**
+   * The child model instance of the relation.
+   */
+  protected child: Model
+
+  /**
+   * The foreign key of the parent model.
+   */
+  protected foreignKey: string
+
+  /**
+   * The owner key of the parent model.
+   */
+  protected ownerKey: string
+
+  /**
+   * Create a new has-many-by relation instance.
+   */
+  constructor(
+    parent: Model,
+    child: Model,
+    foreignKey: string,
+    ownerKey: string
+  ) {
+    super(parent, child)
+    this.foreignKey = foreignKey
+    this.ownerKey = ownerKey
+
+    // In the underlying base relation class, this property is referred to as
+    // the "parent" as most relations are not inversed. But, since this
+    // one is, we will create a "child" property for improved readability.
+    this.child = child
+  }
+
+  /**
+   * Get all related models for the relationship.
+   */
+  getRelateds(): Model[] {
+    return [this.child]
+  }
+
+  /**
+   * Define the normalizr schema for the relation.
+   */
+  define(schema: Schema): NormalizrSchema {
+    return schema.many(this.child)
+  }
+
+  /**
+   * Attach the relational key to the given relation.
+   */
+  attach(record: Element, child: Element): void {
+    // If the child doesn't contain the owner key, just skip here. This happens
+    // when child items have uid attribute as its primary key, and it's missing
+    // when inserting records. Those ids will be generated later and will be
+    // looped again. At that time, we can attach the correct owner key value.
+    if (child[this.ownerKey] === undefined) {
+      return
+    }
+
+    if (!record[this.foreignKey]) {
+      record[this.foreignKey] = []
+    }
+
+    this.attachIfMissing(record[this.foreignKey], child[this.ownerKey])
+  }
+
+  /**
+   * Push owner key to foregin key array if owner key doesn't exist in foreign
+   * key array.
+   */
+  protected attachIfMissing(
+    foreignKey: (string | number)[],
+    ownerKey: string | number
+  ): void {
+    if (foreignKey.indexOf(ownerKey) === -1) {
+      foreignKey.push(ownerKey)
+    }
+  }
+
+  /**
+   * Set the constraints for an eager load of the relation.
+   */
+  addEagerConstraints(query: Query, models: Collection): void {
+    query.whereIn(this.ownerKey, this.getEagerModelKeys(models))
+  }
+
+  /**
+   * Gather the keys from a collection of related models.
+   */
+  protected getEagerModelKeys(models: Collection): (string | number)[] {
+    return models.reduce<(string | number)[]>((keys, model) => {
+      return [...keys, ...model[this.foreignKey]]
+    }, [])
+  }
+
+  /**
+   * Match the eagerly loaded results to their parents.
+   */
+  match(relation: string, models: Collection, results: Collection): void {
+    const dictionary = results.reduce<Record<string, Model>>((dic, result) => {
+      dic[result[this.ownerKey]] = result
+
+      return dic
+    }, {})
+
+    models.forEach((model) => {
+      const relatedModels = this.getRelatedModels(
+        dictionary,
+        model[this.foreignKey]
+      )
+
+      model.$setRelation(relation, relatedModels)
+    })
+  }
+
+  /**
+   * Get all related models from the given dictionary.
+   */
+  protected getRelatedModels(
+    dictionary: Record<string, Model>,
+    keys: (string | number)[]
+  ): Model[] {
+    return keys.reduce<Model[]>((items, key) => {
+      const item = dictionary[key]
+
+      item && items.push(item)
+
+      return items
+    }, [])
+  }
+}

src/model/decorators/attributes/relations/HasManyBy.ts

@@ -0,0 +1,19 @@
+import { Model } from '../../../Model'
+import { PropertyDecorator } from '../../Contracts'
+
+/**
+ * Create a has-many-by attribute property decorator.
+ */
+export function HasManyBy(
+  related: () => typeof Model,
+  foreignKey: string,
+  ownerKey?: string
+): PropertyDecorator {
+  return (target, propertyKey) => {
+    const self = target.$self()
+
+    self.setRegistry(propertyKey, () =>
+      self.hasManyBy(related(), foreignKey, ownerKey)
+    )
+  }
+}