Home Reference Source Test
public class | source

ObjectStore

This is the main implementation of an object store. It uses a specified backend (which itself implements the very same interface) and builds upon this backend to answer queries. The main task of this object store is to manage transactions and ensure read isolation on these transactions.

Constructor Summary

Public Constructor
public

constructor(backend: IBackend, db: JungleDB, name: string)

Creates a new object store based on a backend and an underlying database.

Member Summary

Public Members
public get

connected: boolean

public get

indices: Map<string, IIndex>

A map of index names to indices.

public get

Method Summary

Public Methods
public

close(): Promise

Closes the object store and potential connections.

public

count(query: KeyRange): Promise<number>

Returns the count of entries in the given range.

public

createIndex(indexName: string, keyPath: string | Array<string>, options: IndexConfig): *

Creates a new secondary index on the object store.

public

decode(value: *, key: string): *

Method called to decode a single value.

public

deleteIndex(indexName: *, options: function(oldVersion: number, newVersion: number): boolean}): *

Deletes a secondary index from the object store.

public

encode(value: *): *

Method called to encode a single value.

public

get(key: string, options: RetrievalConfig): Promise<*>

Returns a promise of the object stored under the given primary key.

public

getSync(key: string, options: SyncRetrievalConfig): *

Returns the object stored under the given primary key.

public

index(indexName: string): IIndex

Returns the index of the given name.

public

isCached(key: string): boolean

A check whether a certain key is cached.

public

isSynchronous(): boolean

Checks whether an object store implements the ISynchronousObjectStore interface.

public

keyStream(callback: function(key: string): boolean, ascending: boolean, query: KeyRange): Promise

Iterates over the keys in a given range and direction.

public

keys(query: Query | KeyRange, limit: number): Promise<Set<string>>

Returns a promise of a set of keys fulfilling the given query.

public

maxKey(query: KeyRange): Promise<string>

Returns a promise of the key being maximal for the given range.

public

maxValue(query: KeyRange): Promise<*>

Returns a promise of the object whose primary key is maximal for the given range.

public

minKey(query: KeyRange): Promise<string>

Returns a promise of the key being minimal for the given range.

public

minValue(query: KeyRange): Promise<*>

Returns a promise of the object whose primary key is minimal for the given range.

public

async put(key: string, value: *): Promise<boolean>

Inserts or replaces a key-value pair.

public

async remove(key: string): Promise<boolean>

Removes the key-value pair of the given key from the object store.

public

Creates an in-memory snapshot of the current state.

public

Creates a new synchronous transaction, ensuring read isolation on the most recently successfully committed state.

public

toString(): string

public

toStringFull(): string

public

transaction(enableWatchdog: boolean): Transaction

Creates a new transaction, ensuring read isolation on the most recently successfully committed state.

public

async truncate(): Promise

Empties the object store.

public

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

values(query: Query | KeyRange, limit: number): Promise<Array<*>>

Returns a promise of an array of objects whose primary keys fulfill the given query.

Protected Methods
protected

async _apply(tx: Transaction): Promise<boolean>

An object store is strongly connected to a backend.

protected

async _commitBackend(): Promise<boolean>

Commits the transaction to the backend.

protected

async _commitInternal(tx: Transaction): Promise

Is used to commit the transaction.

protected

_isCommittable(tx: Transaction): boolean

Is used to probe whether a transaction can be committed.

protected

_setParent(parent: *)

Allows to change the backend of a Transaction when the state has been flushed.

protected

async abort(tx: Transaction): Promise<boolean>

This method is only used by transactions internally to abort themselves at the corresponding object store.

protected

async commit(tx: Transaction): Promise<boolean>

This method is only used by transactions internally to commit themselves to the corresponding object store.

Public Constructors

public constructor(backend: IBackend, db: JungleDB, name: string) source

Creates a new object store based on a backend and an underlying database. The database is only used to determine the connection status.

Params:

NameTypeAttributeDescription
backend IBackend

The backend underlying this object store.

db JungleDB

The database underlying the backend.

name string
  • optional

The name of the object store if existent.

Public Members

public get connected: boolean 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 jungleDB: JungleDB source

Public Methods

public close(): Promise source

Closes the object store and potential connections.

Return:

Promise

The promise resolves after closing the object store.

public 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:

NameTypeAttributeDescription
query KeyRange
  • optional

Return:

Promise<number>

public createIndex(indexName: string, keyPath: string | Array<string>, options: IndexConfig): * source

Creates a new secondary index on the object store. Currently, all secondary indices are non-unique. They are defined by a key within the object or alternatively a path through the object to a specific subkey. For example, ['a', 'b'] could be used to use 'key' as the key in the following object: { 'a': { 'b': 'key' } } Secondary indices may be multiEntry, i.e., if the keyPath resolves to an iterable object, each item within can be used to find this entry. If a new object does not possess the key path associated with that index, it is simply ignored.

This function may only be called before the database is connected. Moreover, it is only executed on database version updates or on first creation.

Params:

NameTypeAttributeDescription
indexName string

The name of the index.

keyPath string | Array<string>
  • optional

The path to the key within the object. May be an array for multiple levels.

options IndexConfig
  • optional

An options object.

Return:

*

public decode(value: *, key: string): * source

Method called to decode a single value.

Params:

NameTypeAttributeDescription
value *

Value to be decoded.

key string

Key corresponding to the value.

Return:

*

The decoded value.

public deleteIndex(indexName: *, options: function(oldVersion: number, newVersion: number): boolean}): * source

Deletes a secondary index from the object store.

Params:

NameTypeAttributeDescription
indexName *
options function(oldVersion: number, newVersion: number): boolean}
  • optional

Return:

*

public encode(value: *): * source

Method called to encode a single value.

Params:

NameTypeAttributeDescription
value *

Value to be encoded.

Return:

*

The encoded value.

public 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:

NameTypeAttributeDescription
key string

The primary key to look for.

options RetrievalConfig
  • optional

Advanced retrieval options.

Return:

Promise<*>

A promise of the object stored under the given key, or undefined if not present.

public getSync(key: string, options: SyncRetrievalConfig): * source

Returns the object stored under the given primary key. Resolves to undefined if the key is not present in the object store.

Params:

NameTypeAttributeDescription
key string

The primary key to look for.

options SyncRetrievalConfig
  • optional

Advanced retrieval options.

Return:

*

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:

NameTypeAttributeDescription
indexName string

The name of the requested index.

Return:

IIndex

The index associated with the given name.

public isCached(key: string): boolean source

A check whether a certain key is cached.

Params:

NameTypeAttributeDescription
key string

The key to check.

Return:

boolean

A boolean indicating whether the key is already in the cache.

public isSynchronous(): boolean source

Checks whether an object store implements the ISynchronousObjectStore interface.

Return:

boolean

The transaction object.

public 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:

NameTypeAttributeDescription
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 keys(query: Query | KeyRange, limit: number): 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.

Params:

NameTypeAttributeDescription
query Query | KeyRange
  • optional

Optional query to check keys against.

limit number
  • optional

Limits the number of results if given.

Return:

Promise<Set<string>>

A promise of the set of keys relevant to the query.

public 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:

NameTypeAttributeDescription
query KeyRange
  • optional

Optional query to check keys against.

Return:

Promise<string>

A promise of the key relevant to the query.

public 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:

NameTypeAttributeDescription
query KeyRange
  • optional

Optional query to check keys against.

Return:

Promise<*>

A promise of the object relevant to the query.

public 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:

NameTypeAttributeDescription
query KeyRange
  • optional

Optional query to check keys against.

Return:

Promise<string>

A promise of the key relevant to the query.

public 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:

NameTypeAttributeDescription
query KeyRange
  • optional

Optional query to check keys against.

Return:

Promise<*>

A promise of the object relevant to the query.

public async put(key: string, value: *): Promise<boolean> source

Inserts or replaces a key-value pair. Implicitly creates a transaction for this operation and commits it.

Params:

NameTypeAttributeDescription
key string

The primary key to associate the value with.

value *

The value to write.

Return:

Promise<boolean>

A promise of the success outcome.

public async remove(key: string): Promise<boolean> source

Removes the key-value pair of the given key from the object store. Implicitly creates a transaction for this operation and commits it.

Params:

NameTypeAttributeDescription
key string

The primary key to delete along with the associated object.

Return:

Promise<boolean>

A promise of the success outcome.

public snapshot(): Snapshot source

Creates an in-memory snapshot of the current 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.

Return:

Snapshot

public synchronousTransaction(enableWatchdog: boolean): SynchronousTransaction source

Creates a new synchronous transaction, ensuring read isolation on the most recently successfully committed state.

WARNING: If not all required key-value-pairs are preloaded, the results of any call on a synchronous transaction might be wrong. Only use synchronous transactions, if unavoidable.

Params:

NameTypeAttributeDescription
enableWatchdog boolean
  • optional

Return:

SynchronousTransaction

The synchronous transaction object.

public toString(): string source

Return:

string

public toStringFull(): string source

Return:

string

public transaction(enableWatchdog: boolean): Transaction source

Creates a new transaction, ensuring read isolation on the most recently successfully committed state.

Params:

NameTypeAttributeDescription
enableWatchdog boolean
  • optional

Return:

Transaction

The transaction object.

public async truncate(): Promise source

Empties the object store.

Return:

Promise

The promise resolves after emptying the object store.

public 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:

NameTypeAttributeDescription
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 values(query: Query | KeyRange, limit: number): 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.

Params:

NameTypeAttributeDescription
query Query | KeyRange
  • optional

Optional query to check keys against.

limit number
  • optional

Limits the number of results if given.

Return:

Promise<Array<*>>

A promise of the array of objects relevant to the query.

Protected Methods

protected async _apply(tx: Transaction): Promise<boolean> source

An object store is strongly connected to a backend. Hence, it does not store anything by itself and the _apply method is not supported.

Params:

NameTypeAttributeDescription
tx Transaction

Return:

Promise<boolean>

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.

Params:

NameTypeAttributeDescription
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:

NameTypeAttributeDescription
tx Transaction

The transaction to be applied.

Return:

boolean

Whether a commit will be successful.

protected _setParent(parent: *) source

Allows to change the backend of a Transaction when the state has been flushed.

Params:

NameTypeAttributeDescription
parent *

protected async abort(tx: Transaction): Promise<boolean> source

This method is only used by transactions internally to abort themselves at the corresponding object store. Thus, the tx argument is non-optional.

Params:

NameTypeAttributeDescription
tx Transaction

The transaction to be aborted.

Return:

Promise<boolean>

A promise of the success outcome.

protected async commit(tx: Transaction): Promise<boolean> source

This method is only used by transactions internally to commit themselves to the corresponding object store. Thus, the tx argument is non-optional. A call to this method checks whether the given transaction can be applied and pushes it to the stack of applied transactions. When there is no other transaction requiring to enforce read isolation, the state will be flattened and all transactions will be applied to the backend.

Params:

NameTypeAttributeDescription
tx Transaction

The transaction to be applied.

Return:

Promise<boolean>

A promise of the success outcome.