Debian Codegraph @

lib/orm/associations/association.js

raw
1 import { dasherize } from "../../utils/inflector";
2
3 /**
4 Associations represent relationships between your Models.
5
6 The `hasMany` and `belongsTo` helpers are how you actually define relationships:
7
8 ```js
9 import { createServer, Model, hasMany, belongsTo }
10
11 createServer({
12 models: {
13 user: Model.extend({
14 comments: hasMany()
15 }),
16 comments: Model.extend({
17 user: belongsTo()
18 })
19 }
20 })
21 ```
22
23 View [the Relationships](https://miragejs.com/docs/main-concepts/relationships/) guide to learn more about setting up relationships.
24
25 Each usage of the helper registers an Association (either a `HasMany` association or `BelongsTo` association) with your server's `Schema`. You can access these associations using either the `schema.associationsFor()` method, or the `associations` property on individual model instances.
26
27 You can then introspect the associations to do things like dynamically build up your JSON response in your serializers.
28
29 @class Association
30 @constructor
31 @public
32 */
33 export default class Association {
34 constructor(modelName, opts) {
35 /**
36 The modelName of the associated model.
37
38 For example, given this configuration
39
40 ```js
41 createServer({
42 models: {
43 user: Model,
44 comment: Model.extend({
45 user: belongsTo()
46 })
47 }
48 })
49 ```
50
51 the association's `modelName` would be `user`.
52
53 Note that an association's `modelName` and the `name` can be different. This is because Mirage supports multiple relationships of the same type:
54
55 ```js
56 createServer({
57 models: {
58 user: Model,
59 comment: Model.extend({
60 author: belongsTo('user'),
61 reviewer: belongsTo('user')
62 })
63 }
64 })
65 ```
66
67 For both these relationships, the `modelName` is `user`, but the first association has a `name` of `author` while the second has a `name` of `reviewer`.
68
69 @property
70 @type {String}
71 @public
72 */
73 this.modelName = undefined; // hack to add ESDOC info. Any better way?
74
75 if (typeof modelName === "object") {
76 // Received opts only
77 this.modelName = undefined;
78 this.opts = modelName;
79 } else {
80 // The modelName of the association. (Might not be passed in - set later
81 // by schema).
82 this.modelName = modelName ? dasherize(modelName) : "";
83 this.opts = opts || {};
84 }
85
86 /**
87 The name of the association, which comes from the property name that was used to define it.
88
89 For example, given this server definition
90
91 ```js
92 createServer({
93 models: {
94 user: Model,
95 comment: Model.extend({
96 author: belongsTo('user')
97 })
98 }
99 })
100 ```
101
102 the association's `name` would be `author`.
103
104 The name is used by Mirage to define foreign keys on the model (`comment.authorId` in this case), among other things.
105
106 @property
107 @type {String}
108 @public
109 */
110 this.name = "";
111
112 // The modelName that owns this association
113 this.ownerModelName = "";
114 }
115
116 /**
117 A setter for schema, since we don't have a reference at constuction time.
118
119 @method setSchema
120 @public
121 @hide
122 */
123 setSchema(schema) {
124 this.schema = schema;
125 }
126
127 /**
128 Returns a Boolean that's true if the association is self-referential, i.e. if a model has an association with itself.
129
130 For example, given
131
132 ```js
133 createServer({
134 models: {
135 user: Model.extend({
136 friends: hasMany('user')
137 })
138 }
139 })
140 ```
141
142 then
143
144 ```js
145 server.schema.associationsFor('user').friends.isReflexive // true
146 ```
147
148 @method isReflexive
149 @return {Boolean}
150 @public
151 */
152 isReflexive() {
153 let isExplicitReflexive = !!(
154 this.modelName === this.ownerModelName && this.opts.inverse
155 );
156 let isImplicitReflexive = !!(
157 this.opts.inverse === undefined && this.ownerModelName === this.modelName
158 );
159
160 return isExplicitReflexive || isImplicitReflexive;
161 }
162
163 /**
164 Returns a Boolean that's true if the association is polymorphic:
165
166 For example, given
167
168 ```js
169 createServer({
170 models: {
171 comment: Model.extend({
172 commentable: belongsTo({ polymorphic: true })
173 })
174 }
175 })
176 ```
177
178 then
179
180 ```js
181 server.schema.associationsFor('comment').commentable.isPolymorphic // true
182 ```
183
184 Check out [the guides on polymorphic associations](https://miragejs.com/docs/main-concepts/relationships/#polymorphic) to learn more.
185
186 @accessor isPolymorphic
187 @type {Boolean}
188 @public
189 */
190 get isPolymorphic() {
191 return this.opts.polymorphic;
192 }
193
194 /**
195 Returns either the string `"hasMany"` or `"belongsTo"`, based on the association type.
196
197 @accessor
198 @type {String}
199 @public
200 */
201 get type() {
202 throw new Error(
203 "Subclasses of Association must implement a getter for type"
204 );
205 }
206
207 /**
208 Returns the name used for the association's foreign key.
209
210 ```js
211 let server = createServer({
212 models: {
213 user: Model,
214 post: Model.extend({
215 fineAuthor: belongsTo("user"),
216 comments: hasMany()
217 }),
218 comment: Model
219 }
220 });
221
222 let associations = server.associationsFor('post')
223
224 associations.fineAuthor.foreignKey // fineAuthorId
225 associations.comments.foreignKey // commentIds
226 ```
227
228 @accessor
229 @type {String}
230 @public
231 */
232 get foreignKey() {
233 return this.getForeignKey();
234 }
235
236 /**
237 @hide
238 */
239 get identifier() {
240 throw new Error(
241 "Subclasses of Association must implement a getter for identifier"
242 );
243 }
244 }