@treelab/treelab/README.md

# Usage

The Treelab Typescript API provides an easy way to integrate Treelab with any external system. The API closely follows REST semantics, uses JSON to encode objects, and relies on standard HTTP codes to signal operation outcomes.

## Installation

Using npm:

```typescript
npm install @treelab/treelab
```

Using yarn:

```typescript
yarn add @treelab/treelab
```

# Object

## Workspace

A workspace contains a collection of cores.

## Core

A core contains a collection of tables. A table can belong to multiple Cores.

## Table

A table is a collection of fields and rows. Each table is also made up of a series of different views.

## Views

A view is essentially a materialized view of a table's data. The same table data can be visualized in a variety of different ways. The current view types supported are:

- `Grid View`
- `Timeline View`
- `List View`
- `Form View (*After alpha release)`
- `Kanban View (*After alpha release)`

Views can not only be used to create interactive visualizations, but it can also be used to pass data from one user/process to another. By applying different filter conditions, the admin user can essentially configure data flow by inviting different users to different views.

## Field Types

Treelab has a lot of rich field types but the main field types are:

- `Text`
- `Number`
- `Record Reference`
- `Table Reference`
- `Core Reference`
- `Select`
- `Multi-Select`
- `Multi-Attachment`

# Events

Treelab is an event-driven system that encodes all state and data changes within the system into a series of `events`. These `events` are then written into a series of different `topics`, which can then be consumed by different parties for processing. Treelab's Typescript SDK abstracts these events into different objects that can then be used to read and write data from Treelab.

```typescript
// Example
EventPayload {
  eventname: 'creb5528ed9c50539b8.CoreCreated',
  workspaceid: 'wspb5506fe4160c6310',
  coreid: 'creb5528ed9c50539b8',
  tableid: '',
  columnid: '',
  rowid: '',
  corename: 'core name',
  color: 'dark',
  icon: 'check',
  tablename: '',
  columnconfig: undefined,
  view: undefined,
  value: undefined,
  metadata: { source: 'USER' }
}

```

# Examples

Initialize it with your apiKey:

```typescript
// Reference
import { Treelab } from 'treelab';

// Create instance
const treelab = new Treelab({
  token: 'your_token_here',
});
```

Now you can do some querys or mutations with the instance.

```typescript
// Create workspace
const workspace = await treelab.createWorkspace({ name: 'workspace name' });
```

There are some properties under every instance

```typescript
console.log(workspace.id); // workspace id
console.log(workspace.name); // workspace name
```

```typescript
// Get one core
const core = await workspace.core('coreId');

// Get one table
const table = await core.table('tableId');
```

The table instance contains a map of rows and views as propertity

```typescript
// Map {
//   'viwb5506fe4f384edda' => View {
//     workspaceId: 'wspb5506fe4160c6310',
//     coreId: 'creb5506fe46a88de54',
//     tableId: 'tblb5506fe4ca8408d8',
//     id: 'viwb5506fe4f384edda',
//     name: 'testView',
//     type: 'GRID',
//     columns:
//       Map {
//        'colb5506fe502834416' => [Column],
//        'colb5506fe5028c62d9' => [Column],
//        'colb5506fe502004bdd' => [Column]
//       }
//     }
//   }
console.log(table.views);

// Map {
//   'rowb5506fe58205e2f6' => Row {
//     workspaceId: 'wspb5506fe4160c6310',
//     coreId: 'creb5506fe46a88de54',
//     tableId: 'tblb5506fe4ca8408d8',
//     id: 'rowb5506fe58205e2f6',
//     rowData:
//       Map {
//        'colb5506fe502834416' => [Cell],
//        'colb5506fe502004bdd' => [Cell],
//        'colb5506fe5028c62d9' => [Cell]
//       }
//     }
//   }
console.log(table.rows);
```

Listen to a instance

```typescript
const subscription = core.onUpdated(e => {
  // do something here
});
subscription.unsubscribe();
core.on(e => {
  // listen all events under the core
});
```

# Treelab object array class

All `Treelab object array` classes have an attribute, and all classes will have a select and sort method to filter or sort, and have the same listener method as a single object to batch listen for objectss.

```typescript
// Get core object array class
const coreArrayClass = await workspace.cores();

// Get table object array class from creating
const tableArrayClass = await core.createTables(...);

// Get an array of all tables: [Table, Table...]
console.log(tableArrayClass.tables);

// Get three tables
const selectedTableArrayClass = await tableArrayClass.select(3);

// Get filtered tables
const filteredTableArrayClass = await tableArrayClass.select((i) => i.name === 'table name'));

// Get sorted tables by asc(Sort like `arrayObject.sort(sortby)`)
const filteredTableArrayClass = await tableArrayClass.sort((a, b) => a.name.localeCompare(b.name));

// Listen for all abjects
const subscriptions = tableArrayClass.onCellUpdated(e => {
  // do something here
})
```

# API

## Treelab

### createWorkspace

```typescript
treelab.createWorkspace(createWorkspaceInput:{ name: string }): Promise<Workspace>;

// Example
const workspace = await treelab.createWorkspace({ name: 'workspace name' });
```

### createWorkspaces

```typescript
treelab.createWorkspaces(): Promise<WorkspaceArray>;

// Example
const workspaceArrayClass = await treelab.createWorkspaces([
  { name: 'workspace 1' },
  { name: 'workspace 2' },
]);
```

### workspace

```typescript
treelab.workspace(id: string ): Promise<Workspace>;

// Example
const workspace = await treelab.workspace('wspb5506fe4160c6310');
```

### getWorkspaces

```typescript
treelab.getWorkspaces(): Promise<WorkspaceArray>;

// Example
const workspaceArrayClass = await treelab.getWorkspaces();
```

## Workspace

### createCore

```typescript
treelab.createCore(createCoreInput:{ name: string, color: Color, icon: Icon }): Promise<Core>;

// Example
const workspace = await treelab.createCore({
  name: 'core name',
  color: Color.blue,
  icon: Icon.untitle
});
```

### createCores

```typescript
treelab.createCores(createCoreInput:{ name: string, color: Color, icon: Icon }): Promise<CoreArray>;

// Example
const workspace = await treelab.createCores([
  { name: 'core1', color: Color.blue, icon: Icon.untitle },
  { name: 'core2', color: Color.black, icon: Icon.check }
]);
```

### core

```typescript
workspace.core(id: string ): Promise<Core>;

// Example
const core = await workspace.core('creb5506fe46a88de54');
```

### getCores

```typescript
workspace.getCores(): Promise<CoreArray>;

// Example
const coreArrayClass = await workspace.getCores();
```

### select

```typescript
workspaceArrayClass.select(maxSize: number, filter: FilterFn): WorkspaceArray;

// Example, select 3 workspaces whose names are 'test'
const workspaceArrayClass = await workspaceArrayClass.select(3, (i) => {
  i.name === 'test'
});
```

### sort

```typescript
workspaceArrayClass.sort(sortFn: SortFn): WorkspaceArray;

// Example, sort workspaces in ascending order
// Sort like `arrayObject.sort(sortby)
const workspaceArrayClass = await workspaceArrayClass.sort((a, b) => a.name.localeCompare(b.name));
```

### onCoreCreated

```typescript
workspace.onCoreCreated(cb: EventCallback): Subscription

// Example
workspace.onCoreCreated(e => {
  console.log('workspace.onCoreCreated:', e);
})
```

### onCoreAdded

```typescript
workspace.onCoreAdded(cb: EventCallback): Subscription

// Example
workspace.onCoreAdded(e => {
  console.log('workspace.onCoreAdded:', e);
})
```

### on

Listen every events under the workspace

```typescript
workspace.on(cb: EventCallback): Subscription

// Example
workspace.on(e => {
  console.log('workspace.on:', e);
})
```

## Core

### createTable

```typescript
const table = core.createTable(createTableInput:{
  name: string,
  view?: ViewInput, // defaultView: GRID
  columns?: ColumnConfig[],
  data?: any[][]
}): Promise<Table>;

// Example
const table = await core.createTable({
  name: 'table',
  view: { name: 'view', type: ViewType.GRID },
  columns: [
    { type: ColumnType.TEXT, name: 'f1' },
    { type: ColumnType.TEXT, name: 'f2' },
    { type: ColumnType.TEXT, name: 'f3' },
  ],
  data: [['1', '2', '3'], ['21', '22', '23'], ['31', '32', '33']],
});
```

### createTables

```typescript
const tableArray = core.createTables(createTableInput[]:{
  name: string,
  view?: ViewInput, // defaultView: GRID
  columns?: ColumnConfig[],
  data?: any[][]
}[]): Promise<TableArray>;

// Example, create a 2 * 3 table
const tableArrayClass = await core.createTables([
  {
    name: 'table1',
    view: { name: 'view1', type: ViewType.GRID },
    columns: [
      { type: ColumnType.TEXT, name: 'f1' },
      { type: ColumnType.TEXT, name: 'f2' },
      { type: ColumnType.TEXT, name: 'f3' },
    ],
    data: [['1', '2', '3'], ['21', '22', '23']],
  },
  {
    name: 'table2',
    view: { name: 'view2', type: ViewType.GRID },
    columns: [
      { type: ColumnType.TEXT, name: 'f1' },
      { type: ColumnType.TEXT, name: 'f2' },
      { type: ColumnType.TEXT, name: 'f3' },
    ],
    data: [['1', '2', '3'], ['21', '22', '23']],
  }
]);
```

### table

```typescript
core.table(id: string ): Promise<Table>;

// Example
const table = await core.table('tblb5528eda11885051');
```

### getTables

```typescript
core.getTables(): Promise<TableArray>;

// Example
const tableArrayClass = await core.getTables();
```

### select

```typescript
coreArrayClass.select(maxSize: number, filter: FilterFn): CoreArray;

// Example, select 3 cores whose names are 'test'
const coreArrayClass = await coreArrayClass.select(3, (i) => {
  i.name === 'test'
});
```

### sort

```typescript
coreArrayClass.sort(sortFn: SortFn): CoreArray;

// Example, sort cores in ascending order
// Sort like `arrayObject.sort(sortby)
const coreArrayClass = await coreArrayClass.sort((a, b) => a.name.localeCompare(b.name));
```

### onTableCreated

```typescript
core.onTableCreated(cb: EventCallback): Subscription

// Example
core.onTableCreated(e => {
  console.log('core.onTableCreated:', e);
})
```

### onTableAdded

```typescript
core.onTableAdded(cb: EventCallback): Subscription

// Example
core.onTableAdded(e => {
  console.log('core.onTableAdded:', e);
})
```

### on

Listen every events under the core

```typescript
core.on(cb: EventCallback): Subscription

// Example
core.on(e => {
  console.log('core.on:', e);
})
```

## Table

### addView

```typescript
table.addView(addViewInput: {
  name: string;
  type: ViewType;
}): Promise<View>;

// Example
const view = await table.addView({ name: 'grid view', type: ViewType.GRID });
```

### addRow

```typescript
table.addRow(): Promise<Row>;

// Example
const row = await table.addRow();
```

### table

```typescript
table.addColumn(conlumnConfig: {
  type: ColumnType;
  name: string;
  order?: number;
  visibility?: boolean;
  foreignTableId?: string;
  defaultNumber?: number;
  precision?: number;
  choices?: Choice[];
}): Promise<Column>;

// Example
const column = await table.addColumn({
  type: ColumnType.TEXT,
  name: "column",
});
```

### view

```typescript
table.view(id: string): View;

// Example
const view = await table.view('viwb5506fe6370f0e4b');
```

### updateCell

```typescript
table.updateCell(updateCellInput: { rowId: string, columnId: string, value: Value}): Promise<Cell>;

// Example
const row = await table.updateCell({
  rowId: "rowb545d20fe08226ed",
  columnId: "colb545910eed85035e",
  value: {
    type: ColumnType.TEXT,
    text: "newCell"
  }
});
```

### addRows

```typescript
table.addRows(number: number): Promise<RowArray>;

// Example, add 5 rows
const rowArray = await table.addRows(5);
```

### addColumns

```typescript
table.addColumns(columnConfigs: ColumnConfig[]): Promise<Column>;

// Example
const columnArray = await table.addColumns([
  { type: ColumnType.TEXT, name: "column1" },
  { type: ColumnType.TEXT, name: "column2" },
]);
```

### updateCells

```typescript
table.updateCells(updateCellInput[]: {
  rowId: string;
  columnId: string;
  value: Value;
}[]): Promise<CellArray>;

// Example
const cellArray = await table.updateCells([
  {
  rowId: "rowb545d20fe08226ed",
  columnId: "colb545910eed85035e",
  value: {
    type: ColumnType.TEXT,
    text: "newCell1"
  },
  {
    rowId: "rowb545d20fe08226ec",
    columnId: "colb545910eed85035c",
    value: {
      type: ColumnType.TEXT,
      text: "newCell2"
    }
  }
]);
```

### select

```typescript
tableArrayClass.select(maxSize: number, filter: FilterFn): TableArray;

// Example, select 3 tables whose names are 'test'
const tableArrayClass = await tableArrayClass.select(3, (i) => {
  i.name === 'test'
});
```

### sort

```typescript
tableArrayClass.sort(sortFn: SortFn): TableArray;

// Example, sort tables in ascending order
// Sort like `arrayObject.sort(sortby)
const tableArrayClass = await tableArrayClass.sort((a, b) => a.name.localeCompare(b.name));
```

### onViewAdded

```typescript
table.onViewAdded(cb: EventCallback): Subscription

// Example
table.onViewAdded(e => {
  console.log('table.onViewAdded:', e);
})
```

### onColumnAdded

```typescript
table.onColumnAdded(cb: EventCallback): Subscription

// Example
table.onColumnAdded(e => {
  console.log('table.onColumnAdded:', e);
})
```

### onRowAdded

```typescript
table.onRowAdded(cb: EventCallback): Subscription

// Example
table.onRowAdded(e => {
  console.log('table.onRowAdded:', e);
})
```

### onCellUpdated

```typescript
table.onCellUpdated(cb: EventCallback): Subscription

// Example
table.onCellUpdated(e => {
  console.log('table.onCellUpdated:', e);
})
```

### on

Listen every events under the table

```typescript
table.on(cb: EventCallback): Subscription

// Example
table.on(e => {
  console.log('table.on:', e);
})
```

## View

### column

```typescript
view.column(id: string): View

// Example
const view = await view.column('colb5506fe5028c62d9')
```

### getColumns

```typescript
view.getColumns(): ColumnArray

// Example
const viewArray = await view.getColumns()
```

### row

```typescript
view.row(id: string): Row;

// Example
const row = await view.row('rowb5506fe5eb875868');
```

### getRows

```typescript
view.getRows(): ColumnArray

// Example
const viewArray = await view.getRows()
```

## Row

### cell

```typescript
row.cell(columnId: string): Cell

// Example
const cell = await row.cell('colb5506fe5028c62d9')
```

### onCellUpdated

```typescript
row.onCellUpdated(cb: EventCallback): Subscription

// Example
row.onCellUpdated(e => {
  console.log('row.onCellUpdated:', e);
})
```

### on

```typescript
row.on(cb: EventCallback): Subscription

// Example
row.on(e => {
  console.log('row.on:', e);
})
```

## Column

### cell

```typescript
column.cell(rowId: string): Cell

// Example
const cell = await column.cell('rowb5506fe5eb875868')
```

### onCellUpdated

```typescript
column.onCellUpdated(cb: EventCallback): Subscription

// Example
column.onCellUpdated(e => {
  console.log('column.onCellUpdated:', e);
})
```

### on

```typescript
column.on(cb: EventCallback): Subscription

// Example
column.on(e => {
  console.log('column.on:', e);
})
```

## Cell

### onCellUpdated

```typescript
cell.onCellUpdated(cb: EventCallback): Subscription

// Example
cell.onCellUpdated(e => {
  console.log('cell.onCellUpdated:', e);
})
```

### on

```typescript
cell.on(cb: EventCallback): Subscription

// Example
cell.on(e => {
  console.log('cell.on:', e);
})
```