This section documents the fr namespace — a collection of import helpers and utility functions designed to make data ingestion and lightweight transformation easy in frosts.

The functions in this section allow frosts to read from Excel, CSV, and JSON documents, as well as perform optimized mathematical operations with minimal code.

Table of Contents

Click to Expand/Collapse
  1. Table of Contents
  2. fr.read_range(range: ExcelScript.Range): DataFrame
  3. fr.read_sheet(Sheet: ExcelScript.Worksheet): DataFrame
  4. fr.read_after(Sheet: ExcelScript.Worksheet, n_rows: number, n_cols: number): DataFrame
  5. fr.read_json(json:string):DataFrame
  6. fr.read_csv(input_text: string, errors: ("raise" | "coerce") = "raise",start_index: number=0, line_separator:string = "\n"): DataFrame
  7. Numeric Utility Functions
    1. fr.sum(values: number[]): number
    2. fr.mean(values: number[]): number
    3. fr.min(values: number[]): number
    4. fr.max(values: number[]): number
    5. fr.range(values: number[]): number
    6. fr.product(values: number[]): number
    7. fr.count(values: number[]): number
    8. fr.today:number
    9. toExcelDate(jsDate: Date, include_time:boolean): number
    10. fr.to_numeric(values:(string|number|boolean)[]):number[]

fr.read_range(range: ExcelScript.Range): DataFrame

Reads a specific Excel range and returns it as a DataFrame.

  • Automatically detects headers from the first row.
  • Converts numeric, string, and boolean values automatically.

✅ Use When:

  • You want to extract a portion of a worksheet (e.g. A1:E10).
  • You already have a defined ExcelScript.Range object.

Example:

const sheet = workbook.getActiveWorksheet();
const df = fr.read_range(workbook.getRange("A1:C6"));

fr.read_sheet(Sheet: ExcelScript.Worksheet): DataFrame

Reads the entire used range of a worksheet and returns it as a DataFrame.

  • Automatically pulls from the used area of the input sheet.
  • Expects the first row to contain headers.

✅ Use When:

  • You want to grab a whole worksheet without manually selecting a range.
  • The sheet is formatted like a table (headers in the first row).
const sheet = workbook.getActiveWorksheet();
const df = fr.read_sheet(sheet);

Note: This function has the same behavior as running

const sheet = workbook.getActiveWorksheet();
const df = fr.read_range(sheet.getUsedRange());

fr.read_after(Sheet: ExcelScript.Worksheet, n_rows: number, n_cols: number): DataFrame

Reads the used range after skipping a number of rows and columns, returning the remaining area as a DataFrame.

  • Starts from the current sheet’s used range.
  • Applies an offset of n_rows down and n_cols to the right.
  • Reads the used portion from that new position onward.

✅ Use When:

  • You want to skip headers, metadata, or intro blocks at the top/left of a worksheet.
  • The data table starts after a known number of rows and columns.
const sheet = workbook.getActiveWorksheet();
const df = fr.read_after(sheet, 3, 1); // skips 3 rows and 1 column

Note: This is equivalent to:

const offset = sheet.getUsedRange().getOffsetRange(3, 1).getUsedRange();
const df = fr.read_range(offset);

fr.read_json(json:string):DataFrame

Reads a JSON string and parses it into a DataFrame.

✅ Use When:

  • You’re loading data from an API, file, or serialized string.
  • You’ve previously used df.to_json() to export data.

fr.read_csv(input_text: string, errors: ("raise" | "coerce") = "raise",start_index: number=0, line_separator:string = "\n"): DataFrame

Reads a raw CSV string and returns a DataFrame.

  • errors = "raise" (default): throws if rows have inconsistent lengths (default).
  • errors = "coerce": pads shorter rows with null.
  • start_index: which line contains the headers (default = 0).
  • line_separator: newline character, can be \n or \r\n.

✅ Use When:

  • You’re pasting in raw CSV or reading from a text file.
  • You need to quickly parse data into a usable table.

Example:

    const csv = "Name,Score\nAlice,88\nBob,90";
    const df = fr.read_csv(csv);

Or skipping the first row:

    const csv = "Report From 4/1/2024\nName,Score\nAlice,88\nBob,90";
    const df = fr.read_csv(csv,"coerce",1);

Numeric Utility Functions

The fr namespace provides standard numeric reducers that can be used with .map_cols_numeric() and other operations that expect (values: number[]) => number.

fr.sum(values: number[]): number

Returns the total sum of the values.

fr.sum([1, 2, 3]); // 6

fr.mean(values: number[]): number

Returns the arithmetic average of the values.

fr.mean([2, 4, 6]); // 4

fr.min(values: number[]): number

Returns the smallest number in the array.

fr.min([8, 3, 5]); // 3

fr.max(values: number[]): number

Returns the largest number in the array.

fr.max([8, 3, 5]); // 8

fr.range(values: number[]): number

Returns the range (max - min) of the values.

fr.range([3, 6, 9]); // 6

fr.product(values: number[]): number

Returns the product of all numbers in the array.

fr.product([2, 3, 4]); // 24

fr.count(values: number[]): number

Returns the number of elements in the array.

fr.count([1, 5, 9]); // 3

fr.today:number

Returns today’s date in Excel Numeric Date Format. Useful for timestamping imports / data modifications

toExcelDate(jsDate: Date, include_time:boolean): number

Converts a JavaScript Date into an Excel numerical date

  • jsDate: The Input date to convert to Excel style.
  • include_time: Whether you’d like the time of the JS Date to be held in the Excel Date (default true).
//Create a date that is 1/1/2000
    let y2k = new Date()
    y2k.setFullYear(2000)
    y2k.setMonth(0,1);
    
    //Export it to excel style including the timestamp
    console.log(fr.toExcelDate(y2k));
    //OUTPUT: 36526.799797291664
    
    //Export to excel style without the timestamp
    console.log(fr.toExcelDate(y2k,false))
    //OUTPUT: 36526

fr.to_numeric(values:(string|number|boolean)[]):number[]

Converts an array of strings (or mixed values) to numbers. Non-convertible values become NaN.

const raw = ["100", "200.5", "invalid", "", null];
const converted = fr.to_numeric(raw);
console.log(converted);
// Output: [100, 200.5, NaN, NaN, NaN]

Frost’s flexible and intuitive design makes reading and writing data a breeze — whether you’re pulling from Excel sheets, parsing raw CSV, or working with JSON APIs. With just a few lines of code, you can go from messy inputs to clean, structured DataFrames ready for transformation, analysis, and export.

  • Importing is simple, no matter the source.
  • Exporting gives you full control over format, structure, and target.
  • Everything integrates seamlessly with ExcelScript, Power Automate, and the broader JavaScript ecosystem.

Now that you’ve mastered data input, you’re ready to start really processing data in the DataFrame object!

Return to API Reference