1 | // Copyright IBM Corp. 2018,2019. All Rights Reserved.
|
2 | // Node module: loopback-datasource-juggler
|
3 | // This file is licensed under the MIT License.
|
4 | // License text available at https://opensource.org/licenses/MIT
|
5 |
|
6 | import {Callback, Options, PromiseOrVoid} from './common';
|
7 | import {ModelBase, ModelData} from './model';
|
8 | import {Filter, Where} from './query';
|
9 |
|
10 | /**
|
11 | * Data object for persisted models
|
12 | */
|
13 | export type PersistedData<
|
14 | T extends PersistedModel = PersistedModel
|
15 | > = ModelData<T>;
|
16 |
|
17 | /**
|
18 | * Type of affected count
|
19 | */
|
20 | export interface Count {
|
21 | count: number;
|
22 | }
|
23 |
|
24 | /**
|
25 | * Persisted model
|
26 | */
|
27 | export declare class PersistedModel extends ModelBase {
|
28 | /**
|
29 | * Create new instance of Model, and save to database.
|
30 | *
|
31 | * @param {Object|Object[]} [data] Optional data argument. Can be either a
|
32 | * single model instance or an array of instances.
|
33 | *
|
34 | * @callback {Function} callback Callback function called with `cb(err, obj)` signature.
|
35 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
36 | * @param {Object} models Model instances or null.
|
37 | */
|
38 | static create(
|
39 | data: PersistedData,
|
40 | options?: Options,
|
41 | callback?: Callback<PersistedModel>,
|
42 | ): PromiseOrVoid<PersistedModel>;
|
43 |
|
44 | static create(
|
45 | data: PersistedData[],
|
46 | options?: Options,
|
47 | callback?: Callback<PersistedModel[]>,
|
48 | ): PromiseOrVoid<PersistedModel[]>;
|
49 |
|
50 | /**
|
51 | * Update or insert a model instance
|
52 | * @param {Object} data The model instance data to insert.
|
53 | * @callback {Function} callback Callback function called with `cb(err, obj)` signature.
|
54 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
55 | * @param {Object} model Updated model instance.
|
56 | */
|
57 | static upsert(
|
58 | data: PersistedData,
|
59 | options?: Options,
|
60 | callback?: Callback<PersistedModel>,
|
61 | ): PromiseOrVoid<PersistedModel>;
|
62 |
|
63 | static updateOrCreate(
|
64 | data: PersistedData,
|
65 | options?: Options,
|
66 | callback?: Callback<PersistedModel>,
|
67 | ): PromiseOrVoid<PersistedModel>;
|
68 |
|
69 | static patchOrCreate(
|
70 | data: PersistedData,
|
71 | options?: Options,
|
72 | callback?: Callback<PersistedModel>,
|
73 | ): PromiseOrVoid<PersistedModel>;
|
74 |
|
75 | /**
|
76 | * Update or insert a model instance based on the search criteria.
|
77 | * If there is a single instance retrieved, update the retrieved model.
|
78 | * Creates a new model if no model instances were found.
|
79 | * Returns an error if multiple instances are found.
|
80 | * @param {Object} [where] `where` filter, like
|
81 | * ```
|
82 | * { key: val, key2: {gt: 'val2'}, ...}
|
83 | * ```
|
84 | * <br/>see
|
85 | * [Where filter](http://loopback.io/doc/en/lb2/Where-filter.html#where-clause-for-other-methods).
|
86 | * @param {Object} data The model instance data to insert.
|
87 | * @callback {Function} callback Callback function called with `cb(err, obj)` signature.
|
88 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
89 | * @param {Object} model Updated model instance.
|
90 | */
|
91 | static upsertWithWhere(
|
92 | where: Where,
|
93 | data: PersistedData,
|
94 | options?: Options,
|
95 | callback?: Callback<PersistedModel>,
|
96 | ): PromiseOrVoid<PersistedModel>;
|
97 |
|
98 | static patchOrCreateWithWhere(
|
99 | where: Where,
|
100 | data: PersistedData,
|
101 | options?: Options,
|
102 | callback?: Callback<PersistedModel>,
|
103 | ): PromiseOrVoid<PersistedModel>;
|
104 |
|
105 | /**
|
106 | * Replace or insert a model instance; replace existing record if one is found,
|
107 | * such that parameter `data.id` matches `id` of model instance; otherwise,
|
108 | * insert a new record.
|
109 | * @param {Object} data The model instance data.
|
110 | * @options {Object} [options] Options for replaceOrCreate
|
111 | * @property {Boolean} validate Perform validation before saving. Default is true.
|
112 | * @callback {Function} callback Callback function called with `cb(err, obj)` signature.
|
113 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
114 | * @param {Object} model Replaced model instance.
|
115 | */
|
116 | static replaceOrCreate(
|
117 | data: PersistedData,
|
118 | options?: Options,
|
119 | callback?: Callback<PersistedModel>,
|
120 | ): PromiseOrVoid<PersistedModel>;
|
121 |
|
122 | /**
|
123 | * Finds one record matching the optional filter object. If not found, creates
|
124 | * the object using the data provided as second argument. In this sense it is
|
125 | * the same as `find`, but limited to one object. Returns an object, not
|
126 | * collection. If you don't provide the filter object argument, it tries to
|
127 | * locate an existing object that matches the `data` argument.
|
128 | *
|
129 | * @options {Object} [filter] Optional Filter object; see below.
|
130 | * @property {String|Object|Array} fields Identify fields to include in return result.
|
131 | * <br/>See [Fields filter](http://loopback.io/doc/en/lb2/Fields-filter.html).
|
132 | * @property {String|Object|Array} include See PersistedModel.include documentation.
|
133 | * <br/>See [Include filter](http://loopback.io/doc/en/lb2/Include-filter.html).
|
134 | * @property {Number} limit Maximum number of instances to return.
|
135 | * <br/>See [Limit filter](http://loopback.io/doc/en/lb2/Limit-filter.html).
|
136 | * @property {String} order Sort order: either "ASC" for ascending or "DESC" for descending.
|
137 | * <br/>See [Order filter](http://loopback.io/doc/en/lb2/Order-filter.html).
|
138 | * @property {Number} skip Number of results to skip.
|
139 | * <br/>See [Skip filter](http://loopback.io/doc/en/lb2/Skip-filter.html).
|
140 | * @property {Object} where Where clause, like
|
141 | * ```
|
142 | * {where: {key: val, key2: {gt: val2}, ...}}
|
143 | * ```
|
144 | * <br/>See
|
145 | * [Where filter](http://loopback.io/doc/en/lb2/Where-filter.html#where-clause-for-queries).
|
146 | * @param {Object} data Data to insert if object matching the `where` filter is not found.
|
147 | * @callback {Function} callback Callback function called with `cb(err, instance, created)` arguments. Required.
|
148 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
149 | * @param {Object} instance Model instance matching the `where` filter, if found.
|
150 | * @param {Boolean} created True if the instance does not exist and gets created.
|
151 | */
|
152 | static findOrCreate(
|
153 | filter: Filter,
|
154 | data: PersistedData,
|
155 | options?: Options,
|
156 | callback?: Callback<PersistedModel>,
|
157 | ): PromiseOrVoid<[PersistedModel, boolean]>;
|
158 |
|
159 | /**
|
160 | * Check whether a model instance exists in database.
|
161 | *
|
162 | * @param {id} id Identifier of object (primary key value).
|
163 | *
|
164 | * @callback {Function} callback Callback function called with `(err, exists)` arguments. Required.
|
165 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
166 | * @param {Boolean} exists True if the instance with the specified ID exists; false otherwise.
|
167 | */
|
168 | static exists(
|
169 | id: any,
|
170 | options?: Options,
|
171 | callback?: Callback<boolean>,
|
172 | ): PromiseOrVoid<boolean>;
|
173 |
|
174 | /**
|
175 | * Find object by ID with an optional filter for include/fields.
|
176 | *
|
177 | * @param {*} id Primary key value
|
178 | * @options {Object} [filter] Optional Filter JSON object; see below.
|
179 | * @property {String|Object|Array} fields Identify fields to include in return result.
|
180 | * <br/>See [Fields filter](http://loopback.io/doc/en/lb2/Fields-filter.html).
|
181 | * @property {String|Object|Array} include See PersistedModel.include documentation.
|
182 | * <br/>See [Include filter](http://loopback.io/doc/en/lb2/Include-filter.html).
|
183 | * @callback {Function} callback Callback function called with `(err, instance)` arguments. Required.
|
184 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
185 | * @param {Object} instance Model instance matching the specified ID or null if no instance matches.
|
186 | */
|
187 | static findById(
|
188 | id: any,
|
189 | filter?: Filter,
|
190 | options?: Options,
|
191 | callback?: Callback<boolean>,
|
192 | ): PromiseOrVoid<PersistedModel>;
|
193 |
|
194 | /**
|
195 | * Find all model instances that match `filter` specification.
|
196 | * See [Querying models](http://loopback.io/doc/en/lb2/Querying-data.html).
|
197 | *
|
198 | * @options {Object} [filter] Optional Filter JSON object; see below.
|
199 | * @property {String|Object|Array} fields Identify fields to include in return result.
|
200 | * <br/>See [Fields filter](http://loopback.io/doc/en/lb2/Fields-filter.html).
|
201 | * @property {String|Object|Array} include See PersistedModel.include documentation.
|
202 | * <br/>See [Include filter](http://loopback.io/doc/en/lb2/Include-filter.html).
|
203 | * @property {Number} limit Maximum number of instances to return.
|
204 | * <br/>See [Limit filter](http://loopback.io/doc/en/lb2/Limit-filter.html).
|
205 | * @property {String} order Sort order: either "ASC" for ascending or "DESC" for descending.
|
206 | * <br/>See [Order filter](http://loopback.io/doc/en/lb2/Order-filter.html).
|
207 | * @property {Number} skip Number of results to skip.
|
208 | * <br/>See [Skip filter](http://loopback.io/doc/en/lb2/Skip-filter.html).
|
209 | * @property {Object} where Where clause, like
|
210 | * ```
|
211 | * { where: { key: val, key2: {gt: 'val2'}, ...} }
|
212 | * ```
|
213 | * <br/>See
|
214 | * [Where filter](http://loopback.io/doc/en/lb2/Where-filter.html#where-clause-for-queries).
|
215 | *
|
216 | * @callback {Function} callback Callback function called with `(err, returned-instances)` arguments. Required.
|
217 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
218 | * @param {Array} models Model instances matching the filter, or null if none found.
|
219 | */
|
220 |
|
221 | static find(
|
222 | filter?: Filter,
|
223 | options?: Options,
|
224 | callback?: Callback<PersistedModel>,
|
225 | ): PromiseOrVoid<PersistedModel[]>;
|
226 |
|
227 | /**
|
228 | * Find one model instance that matches `filter` specification.
|
229 | * Same as `find`, but limited to one result;
|
230 | * Returns object, not collection.
|
231 | *
|
232 | * @options {Object} [filter] Optional Filter JSON object; see below.
|
233 | * @property {String|Object|Array} fields Identify fields to include in return result.
|
234 | * <br/>See [Fields filter](http://loopback.io/doc/en/lb2/Fields-filter.html).
|
235 | * @property {String|Object|Array} include See PersistedModel.include documentation.
|
236 | * <br/>See [Include filter](http://loopback.io/doc/en/lb2/Include-filter.html).
|
237 | * @property {String} order Sort order: either "ASC" for ascending or "DESC" for descending.
|
238 | * <br/>See [Order filter](http://loopback.io/doc/en/lb2/Order-filter.html).
|
239 | * @property {Number} skip Number of results to skip.
|
240 | * <br/>See [Skip filter](http://loopback.io/doc/en/lb2/Skip-filter.html).
|
241 | * @property {Object} where Where clause, like
|
242 | * ```
|
243 | * {where: { key: val, key2: {gt: 'val2'}, ...} }
|
244 | * ```
|
245 | * <br/>See
|
246 | * [Where filter](http://loopback.io/doc/en/lb2/Where-filter.html#where-clause-for-queries).
|
247 | *
|
248 | * @callback {Function} callback Callback function called with `(err, returned-instance)` arguments. Required.
|
249 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
250 | * @param {Array} model First model instance that matches the filter or null if none found.
|
251 | */
|
252 | static findOne(
|
253 | filter?: Filter,
|
254 | options?: Options,
|
255 | callback?: Callback<PersistedModel>,
|
256 | ): PromiseOrVoid<PersistedModel>;
|
257 |
|
258 | /**
|
259 | * Destroy all model instances that match the optional `where` specification.
|
260 | *
|
261 | * @param {Object} [where] Optional where filter, like:
|
262 | * ```
|
263 | * {key: val, key2: {gt: 'val2'}, ...}
|
264 | * ```
|
265 | * <br/>See
|
266 | * [Where filter](http://loopback.io/doc/en/lb2/Where-filter.html#where-clause-for-other-methods).
|
267 | *
|
268 | * @callback {Function} callback Optional callback function called with `(err, info)` arguments.
|
269 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
270 | * @param {Object} info Additional information about the command outcome.
|
271 | * @param {Number} info.count Number of instances (rows, documents) destroyed.
|
272 | */
|
273 | static destroyAll(
|
274 | where?: Where,
|
275 | options?: Options,
|
276 | callback?: Callback<Count>,
|
277 | ): PromiseOrVoid<Count>;
|
278 |
|
279 | static remove(
|
280 | where?: Where,
|
281 | options?: Options,
|
282 | callback?: Callback<Count>,
|
283 | ): PromiseOrVoid<Count>;
|
284 |
|
285 | static deleteAll(
|
286 | where?: Where,
|
287 | options?: Options,
|
288 | callback?: Callback<Count>,
|
289 | ): PromiseOrVoid<Count>;
|
290 |
|
291 | /**
|
292 | * Update multiple instances that match the where clause.
|
293 | *
|
294 | * Example:
|
295 | *
|
296 | *```js
|
297 | * Employee.updateAll({managerId: 'x001'}, {managerId: 'x002'}, function(err, info) {
|
298 | * ...
|
299 | * });
|
300 | * ```
|
301 | *
|
302 | * @param {Object} [where] Optional `where` filter, like
|
303 | * ```
|
304 | * { key: val, key2: {gt: 'val2'}, ...}
|
305 | * ```
|
306 | * <br/>see
|
307 | * [Where filter](http://loopback.io/doc/en/lb2/Where-filter.html#where-clause-for-other-methods).
|
308 | * @param {Object} data Object containing data to replace matching instances, if AnyType.
|
309 | *
|
310 | * @callback {Function} callback Callback function called with `(err, info)` arguments. Required.
|
311 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
312 | * @param {Object} info Additional information about the command outcome.
|
313 | * @param {Number} info.count Number of instances (rows, documents) updated.
|
314 | *
|
315 | */
|
316 | static updateAll(
|
317 | where?: Where,
|
318 | data?: PersistedData,
|
319 | options?: Options,
|
320 | callback?: Callback<Count>,
|
321 | ): PromiseOrVoid<Count>;
|
322 |
|
323 | static update(
|
324 | where?: Where,
|
325 | data?: PersistedData,
|
326 | options?: Options,
|
327 | callback?: Callback<Count>,
|
328 | ): PromiseOrVoid<Count>;
|
329 |
|
330 | /**
|
331 | * Destroy model instance with the specified ID.
|
332 | * @param {*} id The ID value of model instance to delete.
|
333 | * @callback {Function} callback Callback function called with `(err)` arguments. Required.
|
334 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
335 | */
|
336 | static destroyById(
|
337 | id: any,
|
338 | options?: Options,
|
339 | callback?: Callback<Count>,
|
340 | ): PromiseOrVoid<Count>;
|
341 |
|
342 | static removeById(
|
343 | id: any,
|
344 | options?: Options,
|
345 | callback?: Callback<Count>,
|
346 | ): PromiseOrVoid<Count>;
|
347 |
|
348 | static deleteById(
|
349 | id: any,
|
350 | options?: Options,
|
351 | callback?: Callback<Count>,
|
352 | ): PromiseOrVoid<Count>;
|
353 |
|
354 | /**
|
355 | * Replace attributes for a model instance whose id is the first input
|
356 | * argument and persist it into the datasource.
|
357 | * Performs validation before replacing.
|
358 | *
|
359 | * @param {*} id The ID value of model instance to replace.
|
360 | * @param {Object} data Data to replace.
|
361 | * @options {Object} [options] Options for replace
|
362 | * @property {Boolean} validate Perform validation before saving. Default is true.
|
363 | * @callback {Function} callback Callback function called with `(err, instance)` arguments.
|
364 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
365 | * @param {Object} instance Replaced instance.
|
366 | */
|
367 | static replaceById(
|
368 | id: any,
|
369 | data: PersistedData,
|
370 | options?: Options,
|
371 | callback?: Callback<PersistedModel>,
|
372 | ): PromiseOrVoid<PersistedModel>;
|
373 |
|
374 | /**
|
375 | * Return the number of records that match the optional "where" filter.
|
376 | * @param {Object} [where] Optional where filter, like
|
377 | * ```
|
378 | * { key: val, key2: {gt: 'val2'}, ...}
|
379 | * ```
|
380 | * <br/>See
|
381 | * [Where filter](http://loopback.io/doc/en/lb2/Where-filter.html#where-clause-for-other-methods).
|
382 | * @callback {Function} callback Callback function called with `(err, count)` arguments. Required.
|
383 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
384 | * @param {Number} count Number of instances.
|
385 | */
|
386 | static count(
|
387 | where?: Where,
|
388 | options?: Options,
|
389 | callback?: Callback<number>,
|
390 | ): PromiseOrVoid<number>;
|
391 |
|
392 | /**
|
393 | * Save model instance. If the instance doesn't have an ID, then calls [create](#persistedmodelcreatedata-cb) instead.
|
394 | * Triggers: validate, save, update, or create.
|
395 | * @options {Object} [options] See below.
|
396 | * @property {Boolean} validate Perform validation before saving. Default is true.
|
397 | * @property {Boolean} throws If true, throw a validation error; WARNING: This can crash Node.
|
398 | * If false, report the error via callback. Default is false.
|
399 | * @callback {Function} callback Optional callback function called with `(err, obj)` arguments.
|
400 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
401 | * @param {Object} instance Model instance saved or created.
|
402 | */
|
403 | save(options?: Options, callback?: Callback<boolean>): PromiseOrVoid<boolean>;
|
404 |
|
405 | /**
|
406 | * Determine if the data model is new.
|
407 | * @returns {Boolean} Returns true if the data model is new; false otherwise.
|
408 | */
|
409 | isNewRecord(): boolean;
|
410 |
|
411 | /**
|
412 | * Deletes the model from persistence.
|
413 | * Triggers `destroy` hook (async) before and after destroying object.
|
414 | * @param {Function} callback Callback function.
|
415 | */
|
416 | destroy(
|
417 | options?: Options,
|
418 | callback?: Callback<boolean>,
|
419 | ): PromiseOrVoid<boolean>;
|
420 |
|
421 | remove(
|
422 | options?: Options,
|
423 | callback?: Callback<boolean>,
|
424 | ): PromiseOrVoid<boolean>;
|
425 |
|
426 | delete(
|
427 | options?: Options,
|
428 | callback?: Callback<boolean>,
|
429 | ): PromiseOrVoid<boolean>;
|
430 |
|
431 | /**
|
432 | * Update a single attribute.
|
433 | * Equivalent to `updateAttributes({name: 'value'}, cb)`
|
434 | *
|
435 | * @param {String} name Name of property.
|
436 | * @param {Mixed} value Value of property.
|
437 | * @callback {Function} callback Callback function called with `(err, instance)` arguments. Required.
|
438 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
439 | * @param {Object} instance Updated instance.
|
440 | */
|
441 | updateAttribute(
|
442 | name: string,
|
443 | value: any,
|
444 | options?: Options,
|
445 | callback?: Callback<boolean>,
|
446 | ): PromiseOrVoid<boolean>;
|
447 |
|
448 | /**
|
449 | * Update set of attributes. Performs validation before updating.
|
450 | *
|
451 | * Triggers: `validation`, `save` and `update` hooks
|
452 | * @param {Object} data Data to update.
|
453 | * @callback {Function} callback Callback function called with `(err, instance)` arguments. Required.
|
454 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
455 | * @param {Object} instance Updated instance.
|
456 | */
|
457 | updateAttributes(
|
458 | data: PersistedData,
|
459 | options?: Options,
|
460 | callback?: Callback<boolean>,
|
461 | ): PromiseOrVoid<boolean>;
|
462 |
|
463 | /**
|
464 | * Replace attributes for a model instance and persist it into the datasource.
|
465 | * Performs validation before replacing.
|
466 | *
|
467 | * @param {Object} data Data to replace.
|
468 | * @options {Object} [options] Options for replace
|
469 | * @property {Boolean} validate Perform validation before saving. Default is true.
|
470 | * @callback {Function} callback Callback function called with `(err, instance)` arguments.
|
471 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
472 | * @param {Object} instance Replaced instance.
|
473 | */
|
474 | replaceAttributes(
|
475 | data: PersistedData,
|
476 | options?: Options,
|
477 | callback?: Callback<boolean>,
|
478 | ): PromiseOrVoid<boolean>;
|
479 |
|
480 | /**
|
481 | * Reload object from persistence. Requires `id` member of `object` to be able to call `find`.
|
482 | * @callback {Function} callback Callback function called with `(err, instance)` arguments. Required.
|
483 | * @param {Error} err Error object; see [Error object](http://loopback.io/doc/en/lb2/Error-object.html).
|
484 | * @param {Object} instance Model instance.
|
485 | */
|
486 | reload(
|
487 | options?: Options,
|
488 | callback?: Callback<PersistedModel>,
|
489 | ): PromiseOrVoid<PersistedModel>;
|
490 |
|
491 | /**
|
492 | * Set the correct `id` property for the `PersistedModel`. Uses the `setId` method if the model is attached to
|
493 | * connector that defines it. Otherwise, uses the default lookup.
|
494 | * Override this method to handle complex IDs.
|
495 | *
|
496 | * @param {*} val The `id` value. Will be converted to the export type that the `id` property specifies.
|
497 | */
|
498 | setId(val: any): void;
|
499 |
|
500 | /**
|
501 | * Get the `id` value for the `PersistedModel`.
|
502 | *
|
503 | * @returns {*} The `id` value
|
504 | */
|
505 |
|
506 | getId(): any;
|
507 |
|
508 | /**
|
509 | * Get the `id` property name of the constructor.
|
510 | *
|
511 | * @returns {String} The `id` property name
|
512 | */
|
513 |
|
514 | getIdName(): string;
|
515 |
|
516 | /**
|
517 | * Get the `id` property name of the constructor.
|
518 | *
|
519 | * @returns {String} The `id` property name
|
520 | */
|
521 | static getIdName(): string;
|
522 | }
|
523 |
|
524 | export type PersistedModelClass = typeof PersistedModel;
|