Hexabase TypeScript SDKを使ってデータストアからデータを取得する

[Hexabase](https://www.hexabase.com/)は企業においても安心して利用できるBaaS（Backend as a Service）を提供しています。多くのBaaSがそうであるように、主にフロントエンド開発者に利用してもらいたいと考えています。そこで現在、TypeScript SDKの開発が進められています。

この記事ではHexabase TypeScript SDKのインストールと、データストアからのデータ取得方法を紹介します。

## インストール

インストールはnpmやyarnを使って行います。

```
# npmの場合
npm install @hexabase/hexabase-js

# yarnの場合
yarn add @hexabase/hexabase-js
```

## インポート

インポートすると、 `HexabaseClient` というオブジェクトが取得できます。

```ts
import { HexabaseClient } from "@hexabase/hexabase-js";
```

## 初期化

HexabaseClientを初期化します。

```js
const client = new HexabaseClient();
```

### 認証

Hexabaseでは業務利用を想定しているため、利用する際に認証情報が必須になります。最初はメールアドレスとパスワードで認証し、その後はトークンを使ってGraphQLにアクセスします。 `client` を使って処理します。

初回の認証は次のようになります。emailとパスワード、またはトークンが必須です。

```ts
client.login({email, password, token});
```

後はこの `client` に対して処理を行います。

## データストアへのアクセス時に必要な情報について

データストアへアクセスする際には以下の情報が必要です。

- データストアID `datastoreId`
- （オプション） プロジェクトID `projectId`

さらにデータ取得を行う際の情報（ページ数、取得件数など） `params` が指定できます。以下がアクセス例です。

```ts
const project = client.currentWorkspace.project(projectId);
const datastore = project.datastore(datastoreId);
const params = {}; // 検索条件用
const result = await datastore.items(params);
```

`params` は次のような情報を指定できます。

| パラメータ名 | 型 | 必須 | 意味 |
|-------------|-------------|-------------|-------------|
| per_page            | 数値 | ○ | 検索結果の件数(省略、または、0を指定すると、全件取得されます）
| page                | 数値 | ○ | ページ数（省略すると1）
| conditions          | [SearchCondition型の配列](#SearchCondition型) |  | 検索条件を指定
| use_or_condition    | 真偽値 |   | conditionsの条件に対してOR条件で検索します（falseまたは指定しない場合は、AND条件が適用されます）
| unread_only         | 真偽値 |   | trueを指定すると、「未読履歴をもつItem」のみの絞込条件がconditionsへ追加されます。
| sort_field_id       | 文字列 |   | ソートするフィールドIDを指定(ソートキーが1fieldのみの場合)
| sort_order          | 文字列 |   | 昇順の場合"asc" 降順の場合"desc"(ソートキーが1fieldのみの場合)
| sort_fields         | [SortField型](#SortField型) |   | ソートキーが複数ある場合に指定します。 sort_field_idに優先してソートに利用されます。 |
| use_default_search  | 真偽値 |   | true or false デフォルト検索条件(注)を適用する場合、trueを指定
| include_links       | 真偽値 |   | true を指定すると、関連するアイテムのIDの配列を取得できます
| include_lookups     | 真偽値 |   | true を指定すると、データベース参照型の参照先アイテム情報を結果に含めます
| return_count_only   | 真偽値 |   | trueを指定すると、totalItemsのみ返却します。itemsは[] (空配列)となります。
| omit_fields_data    | 真偽値 |   | 結果から、fieldsの情報を含めません。（不要な通信データ量を省略できます）
| omit_total_items    | 真偽値 |   | trueを指定すると、totalItemsをカウントしません（より高速になります） totalItemsは0となります。
| data_result_timeout_sec | 数値 |  | 一覧結果取得までのタイムアウト秒数を指定します。タイムアウトした場合は、itemsは[] (空配列)となります。
| total_count_timeout_sec | 数値 |  | 件数取得までのタイムアウト秒数を指定します。タイムアウトした場合は-1が返ります。
| return_number_value | 真偽値 |  | true を指定すると、数値型データがNumberとして出力されます（defaultでは、数値は文字列("123")で返却される）

### SearchCondition型

検索条件を指定するのに使います。

| パラメータ名 | 型 | 必須 | 意味 |
|-------------|-------------|-------------|-------------|
| search_value |  JSON | | 検索する値に合わせたJSONフォーマット | 
| data_type | 文字列 | | 日付の場合のフォーマットを指定 |
| id | 文字列 | | フィールドID |
| rpf_id | 文字列 | | レポートフィールドID |
| exact_match | 真偽値 | | 完全一致とする場合は true |
| not_match | 真偽値 | | 不一致判定用のフラグ |
| include_null | 真偽値 | | nullを許容するかどうか |
| conditions |  SearchCondition型 | | 検索を入れ子に行う場合 |
| use_or_condition | 真偽値 | | conditionsの条件に対してOR条件で検索します（falseまたは指定しない場合は、AND条件が適用されます） |

### SortField型

検索結果をソートする場合に指定します。

| パラメータ名 | 型 | 必須 | 意味 |
|-------------|-------------|-------------|-------------|
| id          | 文字列 |  | フィールド画面ID |
| order       | 文字列 |  | asc（昇順）またはdesc（降順） |

例としては以下のようになります。

```json
 [
	{ id: "FIELD_A", order: "asc"},
	{ id: "FIELD_B", order: "desc"}
]
```

idにフィールド画面ID、orderにソート順を指定します。orderを省略すると昇順（asc）になります。配列で指定した順番で第1ソートキー、第2ソートキーという形で適用されます。

## まとめ

Hexabase TypeScript SDKを使えば、VueやReactなどと連携したWebアプリを素早く開発できるようになります。2023年04月現在絶賛開発を進めていますので、ぜひ試していただいてフィードバックいただければ嬉しいです！

[hexabase/hexabase-js](https://github.com/hexabase/hexabase-js)