Quick Start

This guide walks you through the most common operations with farseer-client.

Initialize the Client

import * as farseer from 'farseer-client';

const client = new farseer.FarseerClient();

Initialize the Tag Map

Most operations require the tag map to be initialized first. This loads all variables, dimension tables, and members into memory for fast lookups.

await client.initTagMap();

tip

Call initTagMap() once at the start of your application. It's cached in memory and does not need to be called again unless you've modified the model structure.

Get Variable Metadata

const revenue = await client.getVariable('Revenue');
console.log(revenue.id);            // 42
console.log(revenue.name);          // "Revenue"
console.log(revenue.dimensionTagIds); // [10, 11, 12]

Get Dimension Table Data

const { table, metadata } = await client.data.loadFarseerDimensionTable('Products');
table.print();
// Outputs:
// | Name      | Description | Category    |
// |-----------|-------------|-------------|
// | Product A | Desc A      | Electronics |
// | Product B | Desc B      | Furniture   |

Export Variable Data

import { ExportRequestFormatEnum } from 'farseer-client';
import * as aq from 'arquero';

const blob = await client.export.exportFormula({
    format: ExportRequestFormatEnum.Csv,
    formula: 'sum("Revenue", "Y2024", "Plan")'
});

const data = aq.fromCSV(await blob.text());
data.print();

Import Data

const importJob = await client.createImportJob({
    title: 'Revenue Import',
    columns: [
        { type: 'DIMENSION_TABLE', dimensionTableName: 'Products' },
        { type: 'DIMENSION_TABLE', dimensionTableName: 'Years' },
        { type: 'VARIABLE', variableName: 'Revenue' },
    ],
    labels: ['auto', 'revenue', '2024']
});

await importJob.addRows([
    ['Product A', 'Y2024', 100000],
    ['Product B', 'Y2024', 200000],
]);
await importJob.flushRows();
await importJob.undoPrevious();  // Undo previous import with same labels
await importJob.commit();

Work with Files

// Navigate folder structure
const file = await client.getItemByPath(['Finance', 'data.xlsx']);

// Download file
const blob = await client.farseerFiles.get(file.reference);
const buffer = Buffer.from(await blob.arrayBuffer());

// Load Excel as Arquero table
const sheets = await client.data.loadXlsxFile(file);

List Users

const users = await client.users.list();
users.forEach(user => {
    console.log(`${user.firstName} ${user.lastName} (${user.email})`);
});

Error Handling

import { handleUnknownError } from 'farseer-client';

async function main() {
    const client = new farseer.FarseerClient();
    // ... your logic
}

main().catch(handleUnknownError);

Or with custom error handling:

main().catch(async (error: any) => {
    if (error && typeof error.text === 'function') {
        console.error(await error.text());
    } else {
        console.error(error);
    }
    process.exit(1);
});

Evaluate Formulas

const revenue = await client.getVariable('Revenue');
const plan = await client.getDimensionMember('Versions', 'Plan');

const cells = await client.evaluator.evaluate({
    filters: [
        ['RV', `$${revenue.id}`],
        ['P', `$${plan.id}`],
    ],
    cellQueries: [
        { type: 'VARIABLE', formula: 'sum(RV,P)' },
    ],
});

console.log(cells[0].value); // 1250000

Quick Reference

const client = new FarseerClient();
await client.initTagMap();

// Metadata
client.getVariable(name)                    // Variable metadata
client.getDimensionTable(name)              // Dimension table metadata
client.getDimensionMember(table, member)    // Dimension member
client.getDimensionMembersForTable(table)   // All members of a table

// Data export
client.export.exportFormula(config)         // Export variable data
client.data.loadFarseerDimensionTable(name) // Export dimension table
client.data.loadFarseerVariable(name, ...dims) // Export variable as table

// Evaluation
client.evaluator.evaluate(request)          // Evaluate formulas
client.cells.calculateOnDemandCells()       // Trigger on-demand calculation

// Data import
client.createImportJob(config)              // Create import job
client.data.importDataTable(config)         // Import from Arquero table
client.model.load(config)                   // Sync dimension structure

// Files
client.getItemByPath(path)                  // Navigate folders
client.farseerFiles.get(reference)          // Download file
client.data.loadXlsxFile(fileItem)          // Load Excel file
client.data.saveToCsvFarseerFile(table, name, folderId) // Save CSV