@tableau/taco-toolkit
Version:
Tableau Connector Toolkit
318 lines (317 loc) • 12.6 kB
TypeScript
import type { fetchArrayBufferType, fetchJsonType, loadCsvDataType, ingestDataRowsType, loadExcelDataType, loadParquetDataType } from '../../eps/sandbox/sdk/fetcher-utils/fetch-utils';
import { parse as csvParse, createDataRows as csvCreateDataRows } from '../../eps/sandbox/sdk/parser-utils/csv-utils';
import { parse as excelParse } from '../../eps/sandbox/sdk/parser-utils/excel-utils';
import { parse as parquetParse } from '../../eps/sandbox/sdk/parser-utils/parquet-utils';
export { AggType, ColumnRole, ColumnType, DataType, GeographicRole, NumberFormat, UnitsFormat, Auth, Fetcher, Parser, AsyncParser, } from '../../eps/sandbox/sdk/sdk-module';
export type { AuthResult } from '../../shared/types/auth-result';
export type { AuthenticateOptions } from '../../eps/extractor/handlers/abstract/auth';
export type { FetchOptions } from '../../eps/extractor/handlers/abstract/fetcher';
export type { ParseOptions, DataContainerBuilder, DataTableBuilder } from '../../eps/extractor/handlers/abstract/parser';
export type { ColumnHeader, ColumnReference } from '../../eps/types/column-header';
export type { DataContainer } from '../../shared/types/data-container';
export type { DataTable } from '../../shared/types/data-table';
export type { DataRow } from '../../shared/types/data-row';
export type { HandlerInput, FileBasedHandlerInput, BasicHandlerInput } from '../../shared/types/handler-input';
export type { Metadata } from '../../shared/types/metadata';
export type { TacoFileParserName } from '../../shared/enums/taco-file-parser';
export { getAuthHeader, getBasicAuthHeader, getOAuthHeader } from '../../shared/auth-credentials';
export { log } from '../../eps/sandbox/sdk/sandbox-sdk';
export declare class FetchUtils {
private constructor();
/**
* Fetch data from an API endpoint.
*
* The method parses the response body as a JSON string, and returns
* a promise which resolves with the parsing result.
*
* @example
* ```ts
* import { FetchUtils } from '@tableau/taco-toolkit/handlers'
*
* const result = await FetchUtils.fetchJson('example.com/api/user', {
* method: 'POST',
* body: {
* id: 'foo',
* }
* })
*
* // Result: { id: 'foo', name: 'bar' }
* ```
*/
static fetchJson: fetchJsonType;
/**
* Fetch binary data from an API endpoint.
*
* The method returns a promise that resolves with an Uint8Array object.
*
* @example
* ```ts
* import { FetchUtils } from '@tableau/taco-toolkit/handlers'
*
* const result = await FetchUtils.fetchArrayBuffer('example.com/api/file')
*
* // Result: a Uint8Array object which contains the file content
* ```
*/
static fetchArrayBuffer: fetchArrayBufferType;
/**
* Fetch CSV data from an API endpoint and ingest it into EPS data storage.
* The function returns a promise that resolves when data ingestion succeeds.
*
* The function is designated for CSV data only. For a data source that provides CSV data in
* multiple files (with same schema), the function may ingest the files into same table.
* If the multiple files all contain header line, setting the option `trimColumnHeader` to `true`
* will let the function skip the header line when ingesting the subsequent files.
* `trimColumnHeader` has no effect when loading the first file for a table.
*
* Note that loading multiple files into the same table must be performed sequentially, meaning
* `loadCsvData` must be called after the promise returned from the previous call is resolved.
*
* The API must be utilized with built-in file parser `taco:csv-file-parser` that
* parses the ingested data from the EPS data storage.
*
* @example
* ```ts
* // handlerInput
* {
* fetcher: 'MyFetcher', // fetcher file name
* parser: 'taco:csv-file-parser', // built-in csv parser name
* name: 'user-table' // identifier of source object, it will be used as table name
* }
* ```
*
* ```ts
* // MyFetcher.ts
* import { FetchUtils } from '@tableau/taco-toolkit/handlers'
*
* export default class MyFetcher extends Fetcher {
* async *fetch(options: FetchOptions) {
* yield await FetchUtils.loadCsvData('example.com/api/user.csv', {
* trimColumnHeader: true
* })
* }
* }
* ```
*/
static loadCsvData: loadCsvDataType;
/**
* Fetch excel data from an API endpoint and ingest it into EPS data storage.
* The function returns a promise that resolves when data ingestion succeeds.
*
* The function fetches the data in a stream fashion.
*
* The loaded data will be associated with the `handlerInput` that triggers the Fetcher,
* and the `name` property is used to identify the workbook, while the sheet names will be used
* as the table names.
*
* The API must be utilized with built-in excel file parser `taco:excel-file-parser`
* that parses the ingested data from the EPS data storage.
*
* @example
* ```ts
* // handlerInput
* {
* fetcher: 'MyFetcher', // fetcher file name
* parser: 'taco:excel-file-parser', // built-in parser name
* name: 'user-table' // identifier of source object, which will be used to identify the workbook
* }
* ```
* ```ts
* // MyFetcher.ts
* import { FetchUtils } from '@tableau/taco-toolkit/handlers'
*
* export default class MyFetcher extends Fetcher {
* async *fetch(options: FetchOptions) {
* yield await FetchUtils.loadExcelData('example.com/api/user.xls')
* }
* }
* ```
*/
static loadExcelData: loadExcelDataType;
/**
* Fetch parquet data from an API endpoint and ingest it into EPS data storage.
* The function returns a promise that resolves when data ingestion succeeds.
*
* The function fetches the data in a stream fashion.
*
* The loaded data will be associated with the `handlerInput` that triggers the Fetcher,
* and uses the `name` property as the table name for the parsed data fetched from API endpoint/s.
*
* The API must be utilized with built-in parquet file parser `taco:parquet-file-parser`
* that parses the ingested data from the EPS data storage.
*
* @example
* ```ts
* // handlerInput
* {
* fetcher: 'MyFetcher', // fetcher file name
* parser: 'taco:parquet-file-parser', // built-in parser name
* name: 'user-table' // identifier of source object, which will be used as table name
* }
* ```
* ```ts
* // MyFetcher.ts for single API endpoint
* import { FetchUtils } from '@tableau/taco-toolkit/handlers'
*
* export default class MyFetcher extends Fetcher {
* async *fetch(options: FetchOptions) {
* yield await FetchUtils.loadParquetData('example.com/api/user.parquet')
* }
* }
* ```
*
* Note: The API can also be used to fetch parquet data from multiple API endpoints and append
* the data together into a single table. The `name` property from the `handlerInput` will be used
* as the table name for the parsed data fetched from multiple API endpoint.
*
* @example
* ```ts
* // MyFetcher.ts for multiple API endpoints
* import { FetchUtils } from '@tableau/taco-toolkit/handlers'
*
* export default class MyFetcher extends Fetcher {
* async *fetch(options: FetchOptions) {
* const urls = [
* 'example.com/api/user1.parquet',
* 'example.com/api/user2.parquet',
* 'example.com/api/user3.parquet'
* ]
* const promises = urls.map((url) => FetchUtils.loadParquetData(url))
* await Promise.all(promises)
* yield
* }
* }
* ```
*/
static loadParquetData: loadParquetDataType;
/**
* Ingest a list of data with `DataRow` type into EPS data storage.
* The method returns a promise that resolves when data ingestion succeeds.
*
* The ingested data will be associated with the `handlerInput` that triggers the Fetcher,
* and uses the `name` property as the table name for the parsed data.
*
* The API must be utilized with built-in file-based parser `taco:data-file-parser`
* that parses the ingested data from the EPS data storage.
*
* @example
* ```ts
* // handlerInput
* {
* fetcher: 'MyFetcher', // fetcher file name
* parser: 'taco:data-file-parser', // built-in data parser name
* name: 'user-table' // identifier of source object, it will be used as table name
* }
* ```
*
* ```ts
* // MyFetcher.ts
* import { FetchUtils, DataRow } from '@tableau/taco-toolkit/handlers'
*
* export default class MyFetcher extends Fetcher {
* async *fetch(options: FetchOptions) {
* const users = await FetchUtils.fetchJson('example.com/api/user')
*
* const rows: DataRow[] = users.map((user) => {
* const { id, name, address: { street, state, country } } = user
* return { id, name, street, state, country }
* })
*
* await FetchUtils.ingestDataRows(rows)
* }
* }
* ```
*/
static ingestDataRows: ingestDataRowsType;
}
export type { FetchJsonOptions, FetchArrayBufferOptions, FetchRequestOptions, LoadDataOptions, LoadCsvDataOptions, } from '../../eps/sandbox/sdk/fetcher-utils/fetch-utils';
export declare class CsvUtils {
private constructor();
/**
* A utility method to parse CSV data into a two-dimensional array.
* Input data could be ArrayBuffer or string.
*
* This function returns a Promise that resolves to an object
* with headers and rows properties.
*
* @example
* ```ts
* import { CsvUtils } from '@tableau/taco-toolkit/handlers'
*
* const rawData: string =
* "Name,Email,Phone Number\n" +
* "User1,user1@example.com,(555)555-5555\n" +
* "User2,user2@example.com,(123)456-7890"
*
* const { headers, rows } = await CsvUtils.parse(rawData, { hasHeader: true})
*
* // result: an object with headers and rows properties
* ```
*/
static parse: typeof csvParse;
/**
* A utility method to convert a two-dimensional array of data
* into an array of {@link DataRow}.
*
* This function returns a Promise that resolves to an array of DataRow.
*
* @example
* ```ts
* import { CsvUtils } from '@tableau/taco-toolkit/handlers'
*
* const rows: string[][] = [
* ["User1", "user1@example.com", "(555)555-5555"],
* ["User2", "user2@example.com", "(123)456-7890"],
* ]
*
* const columnNames: string[] = ["Name", "Email", "Phone Number"]
*
* const result = await CsvUtils.createDataRows(rows, columnNames)
*
* // result: an array of DataRow
* ```
*/
static createDataRows: typeof csvCreateDataRows;
}
export declare class ExcelUtils {
private constructor();
/**
* A utility method to parse Excel data into an array of {@link DataTable}.
*
* This function returns a Promise that resolves to an array of DataTable.
*
* @example
* ```ts
* import { ExcelUtils } from '@tableau/taco-toolkit/handlers'
*
* export default class MyParser extends Parser<Uint8Array> {
* parse(data: Uint8Array, options: ParseOptions): DataContainer {
* const result = await ExcelUtils.parse(data)
* // result: an array of DataTable
* }
* }
* ```
*/
static parse: typeof excelParse;
}
export declare class ParquetUtils {
private constructor();
/**
* A utility method to parse Parquet data into a {@link DataTable} object.
*
* This function returns a Promise that resolves to a DataTable object.
*
* @example
* ```ts
* import { ParquetUtils } from '@tableau/taco-toolkit/handlers'
*
* export default class MyParser extends Parser<Uint8Array> {
* parse(data: Uint8Array, options: ParseOptions): DataContainer {
* const result = await ParquetUtils.parse(data, 'tablename')
* // result: a DataTable object
* }
* }
* ```
*/
static parse: typeof parquetParse;
}