Transaction
Direct Subclass:
Implements:
Transactions are created by calling the transaction method on an ObjectStore object. Transactions ensure read-isolation. On a given state, only one transaction can be committed successfully. Other transactions based on the same state will end up in a conflicted state if committed. Transactions opened after the successful commit of another transaction will be based on the new state and hence can be committed again. Transactions do not check unique constraints of secondary indices before commiting them.
Constructor Summary
| Protected Constructor | ||
| protected |
constructor(objectStore: ObjectStore, parent: IObjectStore, managingBackend: ICommittable, enableWatchdog: boolean) This constructor should only be called by an ObjectStore object. |
|
Member Summary
| Public Members | ||
| public get |
connected: boolean |
|
| public get |
|
|
| public get |
id: number |
|
| public get |
A map of index names to indices. |
|
| public get |
nested: boolean |
|
| public get |
|
|
| public get |
state: Transaction.STATE: * The transaction's current state. |
|
Method Summary
| Public Methods | ||
| public |
async abort(tx: Transaction): Promise<boolean> Aborts a transaction and (if this was the last open transaction) potentially persists the most recent, committed state. |
|
| public |
close(): Promise Alias for abort. |
|
| public |
async commit(tx: Transaction): Promise<boolean> Commits a transaction to the underlying backend. |
|
| public |
Returns the count of entries in the given range. |
|
| public |
decode(value: *, key: string): * Method called to decode a single value. |
|
| public |
encode(value: *): * Method called to encode a single value. |
|
| public |
async get(key: string, options: RetrievalConfig): Promise<*> Returns a promise of the object stored under the given primary key. |
|
| public |
Returns the index of the given name. |
|
| public |
isSynchronous(): boolean Checks whether an object store implements the ISynchronousObjectStore interface. |
|
| public |
async keyStream(callback: function(key: string): boolean, ascending: boolean, query: KeyRange): Promise Iterates over the keys in a given range and direction. |
|
| public |
Returns a promise of a set of keys fulfilling the given query. |
|
| public |
Returns a promise of the key being maximal for the given range. |
|
| public |
Returns a promise of the object whose primary key is maximal for the given range. |
|
| public |
Returns a promise of the key being minimal for the given range. |
|
| public |
Returns a promise of the object whose primary key is minimal for the given range. |
|
| public |
async put(key: string, value: *): Promise Inserts or replaces a key-value pair. |
|
| public |
putSync(key: string, value: *) Inserts or replaces a key-value pair. |
|
| public |
async remove(key: string): Promise Removes the key-value pair of the given key from the object store. |
|
| public |
removeSync(key: string) Removes the key-value pair of the given key from the object store. |
|
| public |
Creates an in-memory snapshot of this state. |
|
| public |
synchronousTransaction(enableWatchdog: boolean): SynchronousTransaction Creates a nested synchronous transaction, ensuring read isolation. |
|
| public |
toString(): string |
|
| public |
toStringShort(): string |
|
| public |
transaction(enableWatchdog: boolean): Transaction Creates a nested transaction, ensuring read isolation. |
|
| public |
async truncate(): Promise Empties the object store. |
|
| public |
async valueStream(callback: function(value: *, key: string): boolean, ascending: boolean, query: KeyRange): Promise Iterates over the keys and values in a given range and direction. |
|
| public |
Returns a promise of an array of objects whose primary keys fulfill the given query. |
|
| Protected Methods | ||
| protected |
async _apply(tx: Transaction): Promise Internally applies a transaction to the transaction's state. This needs to be done in batch (as a db level transaction), i.e., either the full state is updated or no changes are applied. |
|
| protected |
_applySync(tx: Transaction) Non-async version of _apply that does not update snapshots. |
|
| protected |
async _checkConstraints(): Promise<boolean> Is used to check constraints before committing. |
|
| protected |
async _commitBackend(): Promise<boolean> Commits the transaction to the backend. |
|
| protected |
async _commitInternal(tx: Transaction): Promise Is used to commit the transaction to the in memory state. |
|
| protected |
_isCommittable(tx: Transaction): boolean Is used to probe whether a transaction can be committed. |
|
| protected |
_put(key: string, value: *) Internal method for inserting/replacing a key-value pair. |
|
| protected |
_remove(key: string) Internal method for removing a key-value pair. |
|
| protected |
_setParent(parent: *) Allows to change the backend of a Transaction when the state has been flushed. |
|
| protected |
Non-async variant to empty the object store. |
|
Protected Constructors
protected constructor(objectStore: ObjectStore, parent: IObjectStore, managingBackend: ICommittable, enableWatchdog: boolean) source
This constructor should only be called by an ObjectStore object. Our transactions have a watchdog enabled by default, logging a warning after a certain time specified by WATCHDOG_TIMER. This helps to detect unclosed transactions preventing to store the state in the persistent backend.
Params:
| Name | Type | Attribute | Description |
| objectStore | ObjectStore | The object store this transaction belongs to. |
|
| parent | IObjectStore | The backend on which the transaction is based, i.e., another transaction or the real database. |
|
| managingBackend | ICommittable |
|
The object store managing the transactions, i.e., the ObjectStore object. |
| enableWatchdog | boolean |
|
If this is is set to true (default), a warning will be logged if left open for longer than WATCHDOG_TIMER. |
Public Members
public get connected: boolean source
public get dependency: CombinedTransaction source
public get id: number source
public get indices: Map<string, IIndex> source
A map of index names to indices. The index names can be used to access an index.
public get nested: boolean source
public get objectStore: ObjectStore source
public get state: Transaction.STATE: * source
The transaction's current state.
Return:
| Transaction.STATE |
Public Methods
public async abort(tx: Transaction): Promise<boolean> source
Aborts a transaction and (if this was the last open transaction) potentially persists the most recent, committed state.
Params:
| Name | Type | Attribute | Description |
| tx | Transaction |
|
The transaction to be applied, only used internally. |
Return:
| Promise<boolean> | A promise of the success outcome. |
public close(): Promise source
Alias for abort.
Return:
| Promise | The promise resolves after successful abortion of the transaction. |
public async commit(tx: Transaction): Promise<boolean> source
Commits a transaction to the underlying backend. The state is only written to the persistent backend if no other transaction is open. If the commit was successful, new transactions will always be based on the new state. There are two outcomes for a commit: If there was no other transaction committed that was based on the same state, it will be successful and change the transaction's state to COMMITTED (returning true). Otherwise, the state will be CONFLICTED and the method will return false.
Note that transactions may fail since secondary index constraints are not checked in transactions.
Params:
| Name | Type | Attribute | Description |
| tx | Transaction |
|
The transaction to be applied, only used internally. |
Return:
| Promise<boolean> | A promise of the success outcome. |
public async count(query: KeyRange): Promise<number> source
Returns the count of entries in the given range. If the optional query is not given, it returns the count of entries in the object store. If the query is of type KeyRange, it returns the count of entries within the given range.
Params:
| Name | Type | Attribute | Description |
| query | KeyRange |
|
Return:
| Promise<number> |
public decode(value: *, key: string): * source
Method called to decode a single value.
Params:
| Name | Type | Attribute | Description |
| value | * | Value to be decoded. |
|
| key | string | Key corresponding to the value. |
Return:
| * | The decoded value. |
public encode(value: *): * source
Method called to encode a single value.
Params:
| Name | Type | Attribute | Description |
| value | * | Value to be encoded. |
Return:
| * | The encoded value. |
public async get(key: string, options: RetrievalConfig): Promise<*> source
Returns a promise of the object stored under the given primary key. Resolves to undefined if the key is not present in the object store.
Params:
| Name | Type | Attribute | Description |
| key | string | The primary key to look for. |
|
| options | RetrievalConfig |
|
Advanced retrieval options. |
Return:
| Promise<*> | A promise of the object stored under the given key, or undefined if not present. |
public index(indexName: string): IIndex source
Returns the index of the given name. If the index does not exist, it returns undefined.
Params:
| Name | Type | Attribute | Description |
| indexName | string | The name of the requested index. |
public isSynchronous(): boolean source
Checks whether an object store implements the ISynchronousObjectStore interface.
Return:
| boolean | The transaction object. |
public async keyStream(callback: function(key: string): boolean, ascending: boolean, query: KeyRange): Promise source
Iterates over the keys in a given range and direction. The callback is called for each primary key fulfilling the query until it returns false and stops the iteration.
Params:
| Name | Type | Attribute | Description |
| callback | function(key: string): boolean | A predicate called for each key until returning false. |
|
| ascending | boolean | Determines the direction of traversal. |
|
| query | KeyRange | An optional KeyRange to narrow down the iteration space. |
Return:
| Promise | The promise resolves after all elements have been streamed. |
public async keys(query: Query | KeyRange): Promise<Set<string>> source
Returns a promise of a set of keys fulfilling the given query. If the optional query is not given, it returns all keys in the object store. If the query is of type KeyRange, it returns all keys of the object store being within this range. If the query is of type Query, it returns all keys fulfilling the query.
Return:
| Promise<Set<string>> | A promise of the set of keys relevant to the query. |
public async maxKey(query: KeyRange): Promise<string> source
Returns a promise of the key being maximal for the given range. If the optional query is not given, it returns the maximal key. If the query is of type KeyRange, it returns the key being maximal for the given range.
Params:
| Name | Type | Attribute | Description |
| query | KeyRange |
|
Optional query to check keys against. |
Return:
| Promise<string> | A promise of the key relevant to the query. |
public async maxValue(query: KeyRange): Promise<*> source
Returns a promise of the object whose primary key is maximal for the given range. If the optional query is not given, it returns the object whose key is maximal. If the query is of type KeyRange, it returns the object whose primary key is maximal for the given range.
Params:
| Name | Type | Attribute | Description |
| query | KeyRange |
|
Optional query to check keys against. |
Return:
| Promise<*> | A promise of the object relevant to the query. |
public async minKey(query: KeyRange): Promise<string> source
Returns a promise of the key being minimal for the given range. If the optional query is not given, it returns the minimal key. If the query is of type KeyRange, it returns the key being minimal for the given range.
Params:
| Name | Type | Attribute | Description |
| query | KeyRange |
|
Optional query to check keys against. |
Return:
| Promise<string> | A promise of the key relevant to the query. |
public async minValue(query: KeyRange): Promise<*> source
Returns a promise of the object whose primary key is minimal for the given range. If the optional query is not given, it returns the object whose key is minimal. If the query is of type KeyRange, it returns the object whose primary key is minimal for the given range.
Params:
| Name | Type | Attribute | Description |
| query | KeyRange |
|
Optional query to check keys against. |
Return:
| Promise<*> | A promise of the object relevant to the query. |
public async put(key: string, value: *): Promise source
Inserts or replaces a key-value pair.
Params:
| Name | Type | Attribute | Description |
| key | string | The primary key to associate the value with. |
|
| value | * | The value to write. |
Return:
| Promise | The promise resolves after writing to the current object store finished. |
public putSync(key: string, value: *) source
Inserts or replaces a key-value pair.
Params:
| Name | Type | Attribute | Description |
| key | string | The primary key to associate the value with. |
|
| value | * | The value to write. |
public async remove(key: string): Promise source
Removes the key-value pair of the given key from the object store.
Params:
| Name | Type | Attribute | Description |
| key | string | The primary key to delete along with the associated object. |
Return:
| Promise | The promise resolves after writing to the current object store finished. |
public removeSync(key: string) source
Removes the key-value pair of the given key from the object store.
Params:
| Name | Type | Attribute | Description |
| key | string | The primary key to delete along with the associated object. |
public snapshot(): Snapshot source
Creates an in-memory snapshot of this state. This snapshot only maintains the differences between the state at the time of the snapshot and the current state. To stop maintaining the snapshot, it has to be aborted.
public synchronousTransaction(enableWatchdog: boolean): SynchronousTransaction source
Creates a nested synchronous transaction, ensuring read isolation. This makes the current transaction read-only until all sub-transactions have been closed (committed/aborted). The same semantic for commits applies: Only the first transaction that commits will be applied. Subsequent transactions will be conflicted. This behaviour has one exception: If all nested transactions are closed, the outer transaction returns to a normal state and new nested transactions can again be created and committed.
Params:
| Name | Type | Attribute | Description |
| enableWatchdog | boolean |
|
public transaction(enableWatchdog: boolean): Transaction source
Creates a nested transaction, ensuring read isolation. This makes the current transaction read-only until all sub-transactions have been closed (committed/aborted). The same semantic for commits applies: Only the first transaction that commits will be applied. Subsequent transactions will be conflicted. This behaviour has one exception: If all nested transactions are closed, the outer transaction returns to a normal state and new nested transactions can again be created and committed.
Params:
| Name | Type | Attribute | Description |
| enableWatchdog | boolean |
|
public async truncate(): Promise source
Empties the object store.
Return:
| Promise | The promise resolves after emptying the object store. |
public async valueStream(callback: function(value: *, key: string): boolean, ascending: boolean, query: KeyRange): Promise source
Iterates over the keys and values in a given range and direction. The callback is called for each value and primary key fulfilling the query until it returns false and stops the iteration.
Params:
| Name | Type | Attribute | Description |
| callback | function(value: *, key: string): boolean | A predicate called for each value and key until returning false. |
|
| ascending | boolean | Determines the direction of traversal. |
|
| query | KeyRange | An optional KeyRange to narrow down the iteration space. |
Return:
| Promise | The promise resolves after all elements have been streamed. |
public async values(query: Query | KeyRange): Promise<Array<*>> source
Returns a promise of an array of objects whose primary keys fulfill the given query. If the optional query is not given, it returns all objects in the object store. If the query is of type KeyRange, it returns all objects whose primary keys are within this range. If the query is of type Query, it returns all objects whose primary keys fulfill the query.
Return:
| Promise<Array<*>> | A promise of the array of objects relevant to the query. |
Protected Methods
protected async _apply(tx: Transaction): Promise source
Internally applies a transaction to the transaction's state. This needs to be done in batch (as a db level transaction), i.e., either the full state is updated or no changes are applied.
Params:
| Name | Type | Attribute | Description |
| tx | Transaction | The transaction to apply. |
Return:
| Promise | The promise resolves after applying the transaction. |
protected _applySync(tx: Transaction) source
Non-async version of _apply that does not update snapshots. Internally applies a transaction to the transaction's state. This needs to be done in batch (as a db level transaction), i.e., either the full state is updated or no changes are applied.
Params:
| Name | Type | Attribute | Description |
| tx | Transaction | The transaction to apply. |
protected async _checkConstraints(): Promise<boolean> source
Is used to check constraints before committing. If a constraint is not satisfied, the commitable is aborted and an exception is thrown.
Return:
| Promise<boolean> |
Throw:
* |
protected async _commitBackend(): Promise<boolean> source
Commits the transaction to the backend.
Return:
| Promise<boolean> | A promise of the success outcome. |
protected async _commitInternal(tx: Transaction): Promise source
Is used to commit the transaction to the in memory state.
Params:
| Name | Type | Attribute | Description |
| tx | Transaction | The transaction to be applied. |
Return:
| Promise | A promise that resolves upon successful application of the transaction. |
protected _isCommittable(tx: Transaction): boolean source
Is used to probe whether a transaction can be committed. This, for example, includes a check whether another transaction has already been committed.
Params:
| Name | Type | Attribute | Description |
| tx | Transaction |
|
The transaction to be applied, if not given checks for the this transaction. |
Return:
| boolean | Whether a commit will be successful. |
protected _put(key: string, value: *) source
Internal method for inserting/replacing a key-value pair.
Params:
| Name | Type | Attribute | Description |
| key | string | The primary key to associate the value with. |
|
| value | * | The value to write. |
protected _remove(key: string) source
Internal method for removing a key-value pair.
Params:
| Name | Type | Attribute | Description |
| key | string | The primary key to delete along with the associated object. |
protected _setParent(parent: *) source
Allows to change the backend of a Transaction when the state has been flushed.
Params:
| Name | Type | Attribute | Description |
| parent | * |