# TableStore

A table store provides storage for multiple rows of data in block chain and methods for adding, modifying, and deleting data. This is a higher level wrapper for MultiIndex instance.

Any value stored in TableStore must be an instance inherited from Table class.

There are two options to get and search data in the storage. The first is to get data by primary key (u64 value). The second is to pass a value inherited from Table class. The method getPrimaryValue will be used to get a primary key then.

# Constructors

constructor(
  contract: Name,
  scope: Name
)

contract - The Name object with for the contract

Example: `Name.fromString('mycontract')`

scope - The Name object with for the scope of the table. Recommended same as contract name

Example: `Name.fromString('mycontract')`

_Example:

  import { TableStore } from 'proton-tsc'

  const contract = Name.fromString('mycontract');
  const scope = Name.fromString('mycontract');

  const tablestore = new TableStore(contract, scope);

# Instance Methods

```
set(value: T, payer: Name): void
```
Creates new record or updates the existing one in the storage for the provided value and account passed as payer argument.

_Example:
```
tablestore.set(value, contract)
```
```
store(value: T, payer: Name): void
```
Creates new record in the storage for the provided value and account passed as payer argument.

Throws if:
- If the record with provided primary value already exists
_Example:
```
tablestore.store(value, contract)
```
```
update(value: T, payer: Name): void
```
Updates the existing record in the storage for the provided value and account passed as payer argument.

Throws if:
- If the record with provided primary value does not exist
_Example:
```
tablestore.update(value, contract)
```
```
remove(value: T): void
```
Removes the existing record in the storage for the provided value

Throws if:
- If the record with provided primary value does not exist
_Example:
```
tablestore.remove(value)
```
```
get(key: u64): T | null
```
Returns the value for a provided key. null is returned if there is not value found.

_Example:
```
tablestore.get(key)
```
```
requireGet(key: u64, errorMsg: string): T 
```
A wrapper for get method to throw error if no value for the provided key found. Displays the errorMsg when throws.

Throws if:
- If the record with provided primary value does not exist.
_Example:
```
tablestore.requireGet(id, `no recored with ID ${id} found.`)
```
```
exists(pk: u64): bool
```
Checks if the record for provided primary key exist in the table or not.
```
existsValue(value: T): bool
```
Checks if the record for provided value exist in the table or not.
```
next(value: T): T | null
```
Returns the record that is the next after the provided value Throws if:
- If the record for the provided value is the last in the storage
```
previous(value: T): T | null
```
Returns the record that is the previous to the provided value Throws if:
- If no record for the provided value is the first in the storage
```
first(): T | null
```
Returns the first record in the storage. Or null if no records yet.
```
last(): T | null
```
Returns the last record in the storage. Or null if no records yet.
```
isEmpty(): bool
```
Checks if there is any record in the storage

lowerBound(id: u64): T | null

Returns the first element with primary key greater than or equal to the provided primary key.

_Example:

// there are records with ids: 3, 5, 7
const record = tablestore.lowerBound(4)
// will return record with id 5.
const record = tablestore.lowerBound(3)
// will return record with id 3.

upperBound(id: u64): T | null

Returns the first element with primary key less than or equal to the provided primary key.

_Example:

// there are records with ids: 3, 5, 7
const record = tablestore.upperBound(4)
// will return record with id 3.
const record = tablestore.upperBound(5)
// will return record with id 5.

```
availablePrimaryKey: u64
```
Returns the available primary key that can be used to save data. Read-only field
```
getBySecondaryU64(secondaryValue: u64, index: u8): T | null
```
Utility method. Find the first table element that matches secondary value or null if there is no such value in the table secondaryValue is the secondary value to search for. index is the index to search in.
```
nextBySecondaryU64(value: T, index: u8): T | null
```
Utility method. Returns the record that is the next after the provided secondary value. Returns null if there is no such value or the value is the last in the table. value is the secondary value to search for. index is the index to search in.
```
previousBySecondaryU64(value: T, index: u8): T | null
```
Utility method. Returns the record that is the next after the provided secondary value. Returns null if there is no such value or the value is the first in the table. value is the secondary value to search for. index is the index to search in.
```
getBySecondaryU128(secondaryValue: U128, index: u8): T | null
```
The same as getBySecondaryU64 but with extended size of the secondary value
```
getBySecondaryU256(secondaryValue: U256, index: u8): T | null
```
The same as getBySecondaryU64 but with extended size of the secondary value

getBySecondaryF64(secondaryValue: f64, index: u8): T | null

The same as getBySecondaryU64 but with f64 type of the secondary value

← PermissionLevel PublicKey →