@treelab/treelab

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:

npm install @treelab/treelab

Using yarn:

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.

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

// 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.

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

There are some properties under every instance

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

// 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

// 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

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.

// 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

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

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

createWorkspaces

treelab.createWorkspaces(): Promise<WorkspaceArray>;

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

workspace

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

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

getWorkspaces

treelab.getWorkspaces(): Promise<WorkspaceArray>;

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

Workspace

createCore

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

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

createCores

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

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

core

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

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

getCores

workspace.getCores(): Promise<CoreArray>;

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

select

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

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

workspace.onCoreCreated(cb: EventCallback): Subscription

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

onCoreAdded

workspace.onCoreAdded(cb: EventCallback): Subscription

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

on

Listen every events under the workspace

workspace.on(cb: EventCallback): Subscription

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

Core

createTable

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

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

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

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

getTables

core.getTables(): Promise<TableArray>;

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

select

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

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

core.onTableCreated(cb: EventCallback): Subscription

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

onTableAdded

core.onTableAdded(cb: EventCallback): Subscription

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

on

Listen every events under the core

core.on(cb: EventCallback): Subscription

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

Table

addView

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

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

addRow

table.addRow(): Promise<Row>;

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

table

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

table.view(id: string): View;

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

updateCell

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

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

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

addColumns

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

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

updateCells

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

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

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

table.onViewAdded(cb: EventCallback): Subscription

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

onColumnAdded

table.onColumnAdded(cb: EventCallback): Subscription

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

onRowAdded

table.onRowAdded(cb: EventCallback): Subscription

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

onCellUpdated

table.onCellUpdated(cb: EventCallback): Subscription

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

on

Listen every events under the table

table.on(cb: EventCallback): Subscription

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

View

column

view.column(id: string): View

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

getColumns

view.getColumns(): ColumnArray

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

row

view.row(id: string): Row;

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

getRows

view.getRows(): ColumnArray

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

Row

cell

row.cell(columnId: string): Cell

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

onCellUpdated

row.onCellUpdated(cb: EventCallback): Subscription

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

on

row.on(cb: EventCallback): Subscription

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

Column

cell

column.cell(rowId: string): Cell

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

onCellUpdated

column.onCellUpdated(cb: EventCallback): Subscription

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

on

column.on(cb: EventCallback): Subscription

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

Cell

onCellUpdated

cell.onCellUpdated(cb: EventCallback): Subscription

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

on

cell.on(cb: EventCallback): Subscription

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