collection.js
16.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
'use strict';
Object.defineProperty(exports, "__esModule", {
value: true
});
var _lodash = require('lodash');
var _sync = require('./sync');
var _sync2 = _interopRequireDefault(_sync);
var _helpers = require('./helpers');
var _helpers2 = _interopRequireDefault(_helpers);
var _eager = require('./eager');
var _eager2 = _interopRequireDefault(_eager);
var _errors = require('./errors');
var _errors2 = _interopRequireDefault(_errors);
var _collection = require('./base/collection');
var _collection2 = _interopRequireDefault(_collection);
var _promise = require('./base/promise');
var _promise2 = _interopRequireDefault(_promise);
var _createError = require('create-error');
var _createError2 = _interopRequireDefault(_createError);
function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
/**
* @class Collection
* @extends CollectionBase
* @inheritdoc
* @classdesc
*
* Collections are ordered sets of models returned from the database, from a
* {@link Model#fetchAll fetchAll} call. They may be used with a suite of
* {@link http://lodash.com/ Lodash} methods.
*
* @constructor
* @description
*
* When creating a {@link Collection}, you may choose to pass in the initial
* array of {@link Model models}. The collection's {@link Collection#comparator
* comparator} may be included as an option. Passing `false` as the comparator
* option will prevent sorting. If you define an {@link Collection#initialize
* initialize} function, it will be invoked when the collection is created.
*
* @example
* let tabs = new TabSet([tab1, tab2, tab3]);
*
* @param {(Model[])=} models Initial array of models.
* @param {Object=} options
* @param {bool} [options.comparator=false]
* {@link Collection#comparator Comparator} for collection, or `false` to disable sorting.
*/
var BookshelfCollection = _collection2.default.extend({
/**
* @method Collection#through
* @description
* Used to define passthrough relationships - `hasOne`, `hasMany`, `belongsTo`
* or `belongsToMany`, "through" an `Interim` model or collection.
*
* @param {Model} Interim Pivot model.
*
* @param {string=} throughForeignKey
*
* Foreign key in this collection model. By default, the `foreignKey` is assumed to
* be the singular form of the `Target` model's tableName, followed by `_id` /
* `_{{{@link Model#idAttribute idAttribute}}}`.
*
* @param {string=} otherKey
*
* Foreign key in the `Interim` model. By default, the `otherKey` is assumed to
* be the singular form of this model's tableName, followed by `_id` /
* `_{{{@link Model#idAttribute idAttribute}}}`.
*
* @param {string=} throughForeignKeyTarget
*
* Column in the `Target` model which `throughForeignKey` references, if other
* than `Target` model's `id` / `{@link Model#idAttribute idAttribute}`.
*
* @param {string=} otherKeyTarget
*
* Column in this collection model which `otherKey` references, if other
* than `id` / `{@link Model#idAttribute idAttribute}`.
*
* @returns {Collection}
*/
through: function through(Interim, throughForeignKey, otherKey, throughForeignKeyTarget, otherKeyTarget) {
return this.relatedData.through(this, Interim, {
throughForeignKey: throughForeignKey, otherKey: otherKey, throughForeignKeyTarget: throughForeignKeyTarget, otherKeyTarget: otherKeyTarget
});
},
/**
* @method Collection#fetch
* @description
* Fetch the default set of models for this collection from the database,
* resetting the collection when they arrive. If you wish to trigger an error
* if the fetched collection is empty, pass `{require: true}` as one of the
* options to the {@link Collection#fetch fetch} call. A {@link
* Collection#fetched "fetched"} event will be fired when records are
* successfully retrieved. If you need to constrain the query performed by
* `fetch`, you can call the {@link Collection#query query} method before
* calling `fetch`.
*
* *If you'd like to only fetch specific columns, you may specify a `columns`
* property in the options for the `fetch` call.*
*
* The `withRelated` option may be specified to fetch the models of the
* collection, eager loading any specified {@link Relation relations} named on
* the model. A single property, or an array of properties can be specified as
* a value for the `withRelated` property. The results of these relation
* queries will be loaded into a relations property on the respective models,
* may be retrieved with the {@link Model#related related} method.
*
* @fires Collection#fetched
* @throws {Collection.EmptyError}
* Upon a sucessful query resulting in no records returns. Only fired if `require: true` is passed as an option.
*
* @param {Object=} options
* @param {bool} [options.require=false] Trigger a {@link Collection.EmptyError} if no records are found.
* @param {string|string[]} [options.withRelated=[]] A relation, or list of relations, to be eager loaded as part of the `fetch` operation.
* @returns {Promise<Collection>}
*/
fetch: _promise2.default.method(function (options) {
options = options ? (0, _lodash.clone)(options) : {};
return this.sync(options).select().bind(this).tap(function (response) {
if (!response || response.length === 0) {
throw new this.constructor.EmptyError('EmptyResponse');
}
})
// Now, load all of the data onto the collection as necessary.
.tap(this._handleResponse)
// If the "withRelated" is specified, we also need to eager load all of the
// data on the collection, as a side-effect, before we ultimately jump into the
// next step of the collection. Since the `columns` are only relevant to the current
// level, ensure those are omitted from the options.
.tap(function (response) {
if (options.withRelated) {
return this._handleEager(response, (0, _lodash.omit)(options, 'columns'));
}
}).tap(function (response) {
/**
* @event Collection#fetched
*
* @description
* Fired after a `fetch` operation. A promise may be returned from the
* event handler for async behaviour.
*
* @param {Collection} collection The collection performing the {@link Collection#fetch}.
* @param {Object} response Knex query response.
* @param {Object} options Options object passed to {@link Collection#fetch fetch}.
* @returns {Promise}
*/
return this.triggerThen('fetched', this, response, options);
}).catch(this.constructor.EmptyError, function (err) {
if (options.require) {
throw err;
}
this.reset([], { silent: true });
}).return(this);
}),
/**
* @method Collection#count
* @since 0.8.2
* @description
*
* Get the number of records in the collection's table.
*
* @example
*
* // select count(*) from shareholders where company_id = 1 and share > 0.1;
* Company.forge({id:1})
* .shareholders()
* .query('where', 'share', '>', '0.1')
* .count()
* .then(function(count) {
* assert(count === 3);
* });
*
* @param {string} [column='*']
* Specify a column to count - rows with null values in this column will be excluded.
* @param {Object=} options
* Hash of options.
* @returns {Promise<Number>}
* A promise resolving to the number of matching rows.
*/
count: _promise2.default.method(function (column, options) {
if (!(0, _lodash.isString)(column)) {
options = column;
column = undefined;
}
if (options) options = (0, _lodash.clone)(options);
return this.sync(options).count(column);
}),
/**
* @method Collection#fetchOne
* @description
*
* Fetch and return a single {@link Model model} from the collection,
* maintaining any {@link Relation relation} data from the collection, and
* any {@link Collection#query query} parameters that have already been passed
* to the collection. Especially helpful on relations, where you would only
* like to return a single model from the associated collection.
*
* @example
*
* // select * from authors where site_id = 1 and id = 2 limit 1;
* new Site({id:1})
* .authors()
* .query({where: {id: 2}})
* .fetchOne()
* .then(function(model) {
* // ...
* });
*
* @param {Object=} options
* @param {boolean} [options.require=false]
* If `true`, will reject the returned response with a {@link
* Model.NotFoundError NotFoundError} if no result is found.
* @param {(string|string[])} [options.columns='*']
* Limit the number of columns fetched.
* @param {Transaction} options.transacting
* Optionally run the query in a transaction.
*
* @throws {Model.NotFoundError}
* @returns {Promise<Model|null>}
* A promise resolving to the fetched {@link Model model} or `null` if none exists.
*/
fetchOne: _promise2.default.method(function (options) {
var model = new this.model();
model._knex = this.query().clone();
this.resetQuery();
if (this.relatedData) model.relatedData = this.relatedData;
return model.fetch(options);
}),
/**
* @method Collection#load
* @description
* `load` is used to eager load relations onto a Collection, in a similar way
* that the `withRelated` property works on {@link Collection#fetch fetch}.
* Nested eager loads can be specified by separating the nested relations with
* `'.'`.
*
* @param {string|string[]} relations The relation, or relations, to be loaded.
* @param {Object=} options Hash of options.
* @param {Transaction=} options.transacting
*
* @returns {Promise<Collection>} A promise resolving to this {@link
* Collection collection}
*/
load: _promise2.default.method(function (relations, options) {
if (!(0, _lodash.isArray)(relations)) relations = [relations];
options = (0, _lodash.extend)({}, options, { shallow: true, withRelated: relations });
return new _eager2.default(this.models, this.toJSON(options), new this.model()).fetch(options).return(this);
}),
/**
* @method Collection#create
* @description
*
* Convenience method to create a new {@link Model model} instance within a
* collection. Equivalent to instantiating a model with a hash of {@link
* Model#attributes attributes}, {@link Model#save saving} the model to the
* database then adding the model to the collection.
*
* When used on a relation, `create` will automatically set foreign key
* attributes before persisting the `Model`.
*
* ```
* const { courses, ...attributes } = req.body;
*
* Student.forge(attributes).save().tap(student =>
* Promise.map(courses, course => student.related('courses').create(course))
* ).then(student =>
* res.status(200).send(student)
* ).catch(error =>
* res.status(500).send(error.message)
* );
* ```
*
* @param {Object} model A set of attributes to be set on the new model.
* @param {Object=} options
* @param {Transaction=} options.transacting
*
* @returns {Promise<Model>} A promise resolving with the new {@link Modle
* model}.
*/
create: _promise2.default.method(function (model, options) {
options = options != null ? (0, _lodash.clone)(options) : {};
var relatedData = this.relatedData;
model = this._prepareModel(model, options);
// If we've already added things on the query chain,
// these are likely intended for the model.
if (this._knex) {
model._knex = this._knex;
this.resetQuery();
}
return _helpers2.default.saveConstraints(model, relatedData).save(null, options).bind(this).then(function () {
if (relatedData && relatedData.type === 'belongsToMany') {
return this.attach(model, (0, _lodash.omit)(options, 'query'));
}
}).then(function () {
this.add(model, options);
}).return(model);
}),
/**
* @method Collection#resetQuery
* @description
* Used to reset the internal state of the current query builder instance.
* This method is called internally each time a database action is completed
* by {@link Sync}.
*
* @returns {Collection} Self, this method is chainable.
*/
resetQuery: function resetQuery() {
this._knex = null;
return this;
},
/**
* @method Collection#query
* @description
*
* `query` is used to tap into the underlying Knex query builder instance for
* the current collection. If called with no arguments, it will return the
* query builder directly. Otherwise, it will call the specified `method` on
* the query builder, applying any additional arguments from the
* `collection.query` call. If the `method` argument is a function, it will be
* called with the Knex query builder as the context and the first argument.
*
* @example
*
* let qb = collection.query();
* qb.where({id: 1}).select().then(function(resp) {
* // ...
* });
*
* collection.query(function(qb) {
* qb.where('id', '>', 5).andWhere('first_name', '=', 'Test');
* }).fetch()
* .then(function(collection) {
* // ...
* });
*
* collection
* .query('where', 'other_id', '=', '5')
* .fetch()
* .then(function(collection) {
* // ...
* });
*
* @param {function|Object|...string=} arguments The query method.
* @returns {Collection|QueryBuilder}
* Will return this model or, if called with no arguments, the underlying query builder.
*
* @see {@link http://knexjs.org/#Builder Knex `QueryBuilder`}
*/
query: function query() {
return _helpers2.default.query(this, (0, _lodash.toArray)(arguments));
},
/**
* @method Collection#orderBy
* @since 0.9.3
* @description
*
* Specifies the column to sort on and sort order.
*
* The order parameter is optional, and defaults to 'ASC'. You may
* also specify 'DESC' order by prepending a hyphen to the sort column
* name. `orderBy("date", 'DESC')` is the same as `orderBy("-date")`.
*
* Unless specified using dot notation (i.e., "table.column"), the default
* table will be the table name of the model `orderBy` was called on.
*
* @example
*
* Cars.forge().orderBy('color', 'ASC').fetch()
* .then(function (rows) { // ...
*
* @param sort {string}
* Column to sort on
* @param order {string}
* Ascending ('ASC') or descending ('DESC') order
*/
orderBy: function orderBy() {
for (var _len = arguments.length, args = Array(_len), _key = 0; _key < _len; _key++) {
args[_key] = arguments[_key];
}
return _helpers2.default.orderBy.apply(_helpers2.default, [this].concat(args));
},
/**
* @method Collection#query
* @private
* @description Creates and returns a new `Bookshelf.Sync` instance.
*/
sync: function sync(options) {
return new _sync2.default(this, options);
},
/* Ensure that QueryBuilder is copied on clone. */
clone: function clone() {
var cloned = BookshelfCollection.__super__.clone.apply(this, arguments);
if (this._knex != null) {
cloned._knex = cloned._builder(this._knex.clone());
}
return cloned;
},
/**
* @method Collection#_handleResponse
* @private
* @description
* Handles the response data for the collection, returning from the
* collection's `fetch` call.
*/
_handleResponse: function _handleResponse(response) {
var relatedData = this.relatedData;
this.set(response, { silent: true, parse: true }).invokeMap('_reset');
if (relatedData && relatedData.isJoined()) {
relatedData.parsePivot(this.models);
}
},
/**
* @method Collection#_handleEager
* @private
* @description
* Handle the related data loading on the collection.
*/
_handleEager: function _handleEager(response, options) {
return new _eager2.default(this.models, response, new this.model()).fetch(options);
}
}, {
extended: function extended(child) {
/**
* @class Collection.EmptyError
* @description
* Thrown when no records are found by {@link Collection#fetch fetch},
* {@link Model#fetchAll}, or {@link Model.fetchAll} when called with
* the `{require: true}` option.
*/
child.EmptyError = (0, _createError2.default)(this.EmptyError);
}
});
BookshelfCollection.EmptyError = _errors2.default.EmptyError;
exports.default = BookshelfCollection;