Class: UpdateDBO

x2node-dbos~ UpdateDBO

Update database operation implementation (potentially a combination of SQL UPDATE, INSERT and DELETE queries).

new UpdateDBO(dbDriver, recordTypes, rcMonitor, recordTypeDesc, patch [, filterOrFetcher])

Note: The constructor is not accessible from the client code. Instances are created using DBOFactory.
Parameters:
Name Type Argument Description
dbDriver module:x2node-dbos.DBDriver The database driver.
recordTypes module:x2node-records~RecordTypesLibrary Record types library.
rcMonitor module:x2node-dbos.RecordCollectionsMonitor The record collections monitor.
recordTypeDesc module:x2node-records~RecordTypeDescriptor The record type descriptor.
patch module:x2node-patches~RecordPatch The patch.
filterOrFetcher Array.<Array> | module:x2node-dbos~UpdateDBO~recordsFetcher <optional>
Optional filter specification or fetcher function.

Extends

Methods


execute(txOrCon, actor, recordValidators [, filterParams])

Execute the operation.
Parameters:
Name Type Argument Description
txOrCon module:x2node-dbos~Transaction | * The active database transaction, or database connection object compatible with the database driver to have the method automatically organize the transaction around the operation execution.
actor module:x2node-common.Actor <nullable>
Actor executing the DBO.
recordValidators module:x2node-dbos~UpdateDBO~RecordValidators | module:x2node-dbos~UpdateDBO~recordValidator <nullable>
Record validation/normalization functions, or null if none. If function is provided, it is assumed to be the "afterPatch" function.
filterParams Object.<string, *> <optional>
Filter parameters. The keys are parameter names, the values are parameter values. Note, that no value type conversion is performed: strings are used as SQL strings, numbers as SQL numbers, etc. Arrays are expanded into comma-separated lists of element values. Functions are called without arguments and the results are used as values. Otherwise, values can be strings, numbers, Booleans and nulls. If the DBO was built with a fetcher function instead of a filter specification, this argument is made available to the fetcher function in the DBO execution context.
Throws:
If provided filter parameters object is invalid (missing parameter, NaN value or value of unsupported type).
Type
module:x2node-common.X2UsageError
Returns:
The operation result object promise. The promise is rejected with the error object if an error happens during the operation execution (failed "test" operation is not considered an error). Also may be rejected with the provided recordValidator function rejection result.
Type
Promise.<module:x2node-dbos~UpdateDBO~Result>

Type Definitions


recordsFetcher(ctx)

Provides the update DBO with records to update.
Parameters:
Name Type Description
ctx module:x2node-dbos~DBOExecutionContext DBO execution context.
Returns:
The records or a promise of the records. The records must include all properties fetched by default. Also, it is recommended that the fetcher makes sure that the records are exclusively locked in the database.
Type
Array.<Object> | Promise.<Array.<Object>>

recordValidator(record)

Validates the record after applying the patch but before saving it to the database.
Parameters:
Name Type Description
record Object The record after the patch has been applied. The record includes all properties that are fetched by default (by default, that includes all properties that are not views, not calculated and not dependent record references).
Returns:
If returns a promise, it can be either resolved to proceed with the record save or rejected, in which case the whole DBO execution is aborted and the promise returned by the DBO's execute() method is rejected with the record validator's rejection object. If returned value is not a promise (including nothing), the record save continues.
Type
* | Promise

RecordValidators

Record validator functions.
Type:
  • Object
Properties:
Name Type Argument Description
beforePatch module:x2node-dbos~UpdateDBO~recordValidator <optional>
Validator function invoked before applying the patch.
afterPatch module:x2node-dbos~UpdateDBO~recordValidator <optional>
Validator function invoked after applying the patch.

Result

Update DBO execution result object.
Properties:
Name Type Argument Description
records Array.<Object> All patched matched records with all properties that are fetched by default.
updatedRecordIds Array.<(string|number)> Ids of records actually modified by the operation, empty array if none.
testFailed boolean true if any of the matched records were not updated because a "test" patch operation failed.
failedRecordIds Array <optional>
If testFailed is true, this lists the ids of the failed records.