Skip to main content

FitFileViewerUtils

FitFileViewer - API Documentation v29.4.0

FitFileViewer - API Documentation / utils / FitFileViewerUtils

Variable: FitFileViewerUtils

const FitFileViewerUtils: { cleanup: () => void; getAvailableUtils: () => string[]; getUtil: (name: string) => Function | null; isUtilAvailable: (name: string) => boolean; namespace: string; safeExecute: (utilName: string, ...args: any[]) => any; utils: { applyTheme: (theme: string, withTransition: boolean) => void; copyTableAsCSV: (table: DataTable) => Promise<void>; createTables: (dataFrames: Object, containerOverride?: HTMLElement) => void; formatArray: (val: any, digits?: number, options?: { separator?: string; strictValidation?: boolean; }) => any; formatDistance: (meters: number) => string; formatDuration: (seconds: string | number | null | undefined) => string; listenForThemeChange: (onThemeChange: (theme: string) => void) => void; loadTheme: () => string; patchSummaryFields: (obj: Record<string, any>, options?: PatchSummaryFieldsOptions) => Record<string, any>; renderMap: () => void; renderSummary: (data: { sessionMesgs?: Object[]; recordMesgs?: Object[]; lapMesgs?: Object[]; }) => void; renderTable: (container: HTMLElement, title: string, table: Object, index: number) => void; setLoading: (loading: boolean) => void; setTabButtonsEnabled: (enabled: boolean) => void; showFitData: (data: Object, filePath?: string, options?: { resetRenderStates?: boolean; updateUI?: boolean; }) => void; showNotification: (message: string, type?: "error" | "info" | "success" | "warning", duration?: number, options?: NotificationOptions) => Promise<void>; updateActiveTab: (tabId: string) => boolean; updateMapTheme: () => void; updateTabVisibility: (visibleTabId: string | null | undefined) => void; }; validateAllUtils: () => ValidationResults; get version(): string; }

Defined in: utils.js:375

Enhanced namespace management

Type Declaration​

cleanup()​

cleanup: () => void

Cleanup function

Returns​

void

getAvailableUtils()​

getAvailableUtils: () => string[]

Utility management functions

Returns​

string[]

getUtil()​

getUtil: (name: string) => Function | null

Parameters​

name​

string

Utility name

Returns​

Function | null

The utility function or null

isUtilAvailable()​

isUtilAvailable: (name: string) => boolean

Parameters​

name​

string

Utility name

Returns​

boolean

Is utility available

namespace​

namespace: string = CONSTANTS.NAMESPACE

safeExecute()​

safeExecute: (utilName: string, ...args: any[]) => any

Parameters​

utilName​

string

Utility name

args​

...any[]

Arguments to pass

Returns​

any

Result of utility execution

utils​

utils: { applyTheme: (theme: string, withTransition: boolean) => void; copyTableAsCSV: (table: DataTable) => Promise<void>; createTables: (dataFrames: Object, containerOverride?: HTMLElement) => void; formatArray: (val: any, digits?: number, options?: { separator?: string; strictValidation?: boolean; }) => any; formatDistance: (meters: number) => string; formatDuration: (seconds: string | number | null | undefined) => string; listenForThemeChange: (onThemeChange: (theme: string) => void) => void; loadTheme: () => string; patchSummaryFields: (obj: Record<string, any>, options?: PatchSummaryFieldsOptions) => Record<string, any>; renderMap: () => void; renderSummary: (data: { sessionMesgs?: Object[]; recordMesgs?: Object[]; lapMesgs?: Object[]; }) => void; renderTable: (container: HTMLElement, title: string, table: Object, index: number) => void; setLoading: (loading: boolean) => void; setTabButtonsEnabled: (enabled: boolean) => void; showFitData: (data: Object, filePath?: string, options?: { resetRenderStates?: boolean; updateUI?: boolean; }) => void; showNotification: (message: string, type?: "error" | "info" | "success" | "warning", duration?: number, options?: NotificationOptions) => Promise<void>; updateActiveTab: (tabId: string) => boolean; updateMapTheme: () => void; updateTabVisibility: (visibleTabId: string | null | undefined) => void; }

Core utilities object

utils.applyTheme()​

applyTheme: (theme: string, withTransition: boolean) => void

Theme utilities

Apply the given theme to the document body and persist it.

Parameters​
theme​

string

'dark', 'light', or 'auto'

withTransition​

boolean = true

Whether to animate the theme change

Returns​

void

utils.copyTableAsCSV()​

copyTableAsCSV: (table: DataTable) => Promise<void>

Copies the contents of a table as a CSV string to the clipboard

This function serializes each row of the table, handling nested objects by stringifying them. It attempts to use the modern Clipboard API and falls back to the legacy method if necessary.

Parameters​
table​

DataTable

The table object to copy. Must have an objects() method that returns an array of row objects

Returns​

Promise<void>

Throws​

If the table object does not have an objects() method

Example​
// Copy a DataTable to clipboard as CSV
copyTableAsCSV(myDataTable);

utils.createTables()​

createTables: (dataFrames: Object, containerOverride?: HTMLElement) => void

Renders all data tables from the provided dataFrames object into the specified container.

  • Uses Arquero (window.aq) to convert arrays to tables.
  • Renders each table using renderTable().
  • 'recordMesgs' is always rendered first, then other tables alphabetically.
Parameters​
dataFrames​

Object

An object where each key is a table name and the value is an array of row objects.

containerOverride?​

HTMLElement

Optional container element to render tables into. Defaults to element with id 'content-data'.

Note: The renderTable function receives an additional index parameter, which represents the order of the table being rendered.

Returns​

void

utils.formatArray()​

formatArray: (val: any, digits?: number, options?: { separator?: string; strictValidation?: boolean; }) => any

Formats an array or a comma-separated string of numbers to a string with each number rounded to a specified number of decimal digits.

Parameters​
val​

any

The array of numbers, comma-separated string of numbers, or other value to format

digits?​

number = FORMATTING_CONSTANTS.DEFAULT_DECIMAL_DIGITS

The number of decimal digits to round each number to

options?​

Additional formatting options

separator?​

string

Custom separator for joined values

strictValidation?​

boolean

Whether to throw on invalid numbers

Returns​

any

The formatted string of numbers, or the original value if not processable

Throws​

If strictValidation is true and any value cannot be converted to a number

Examples​
// Format array of numbers
formatArray([1.234, 2.567, 3.891]) // "1.23, 2.57, 3.89"
// Format comma-separated string
formatArray("1.234,2.567,3.891", 1) // "1.2, 2.6, 3.9"
// With custom options
formatArray([1.234, 2.567], 3, { separator: " | " }) // "1.234 | 2.567"

utils.formatDistance()​

formatDistance: (meters: number) => string

Formatting utilities

Formats a distance in meters to a string showing both kilometers and miles

Converts the input distance to both metric (kilometers) and imperial (miles) units and returns a formatted string. Invalid inputs (negative, zero, NaN, or non-finite numbers) return an empty string.

Parameters​
meters​

number

The distance in meters to format. Must be a finite positive number.

Returns​

string

The formatted distance as "X.XX km / Y.YY mi", or an empty string if invalid

Example​
formatDistance(1000);     // "1.00 km / 0.62 mi"
formatDistance(5000);     // "5.00 km / 3.11 mi"
formatDistance(-100);     // ""
formatDistance(NaN);      // ""

utils.formatDuration()​

formatDuration: (seconds: string | number | null | undefined) => string

Formats a duration given in seconds into a human-readable string

Handles various input types and formats appropriately:

  • Null/undefined inputs return empty string
  • Invalid inputs throw descriptive errors
  • Less than 60 seconds: "X sec"
  • Less than 1 hour: "Y min Z sec"
  • 1 hour or more: "H hr(s) M min"
Parameters​
seconds​

The duration in seconds

string | number | null | undefined

Returns​

string

The formatted duration string

Throws​

If the input is not a finite number or is negative

Example​
formatDuration(30);        // "30 sec"
formatDuration(90);        // "1 min 30 sec"
formatDuration(3661);      // "1 hr 1 min"
formatDuration(7320);      // "2 hrs 2 min"
formatDuration(null);      // ""
formatDuration(-10);       // throws Error

utils.listenForThemeChange()​

listenForThemeChange: (onThemeChange: (theme: string) => void) => void

Listen for theme change events from the Electron main process and apply the theme.

Parameters​
onThemeChange​

(theme: string) => void

Returns​

void

utils.loadTheme()​

loadTheme: () => string

Load the persisted theme from localStorage, defaulting to 'dark'.

Returns​

string

utils.patchSummaryFields()​

patchSummaryFields: (obj: Record<string, any>, options?: PatchSummaryFieldsOptions) => Record<string, any>

Data processing utilities

Parameters​
obj​

Record<string, any>

options?​

PatchSummaryFieldsOptions = {}

Returns​

Record<string, any>

utils.renderMap()​

renderMap: () => void

Visualization utilities

Returns​

void

utils.renderSummary()​

renderSummary: (data: { sessionMesgs?: Object[]; recordMesgs?: Object[]; lapMesgs?: Object[]; }) => void

Renders a summary of activity data, including main summary and lap summary tables, into the DOM element with id 'content-summary'. Provides "Copy as CSV" buttons for both tables.

The summary is generated from either sessionMesgs or recordMesgs in the input data. If lap data is available (lapMesgs), lap rows are appended to the same table.

Parameters​
data​

The activity data object.

sessionMesgs?​

Object[]

Array of session message objects (optional).

recordMesgs?​

Object[]

Array of record message objects (optional).

lapMesgs?​

Object[]

Array of lap message objects (optional).

Returns​

void

Example​
renderSummary({
  sessionMesgs: [{ total_ascent: 100, total_descent: 80, ... }],
  recordMesgs: [{ timestamp: 123, distance: 1000, speed: 2.5, ... }, ...],
  lapMesgs: [{ lap_index: 1, total_time: 300, ... }, ...]
});

utils.renderTable()​

renderTable: (container: HTMLElement, title: string, table: Object, index: number) => void

Renders a collapsible table section with a header, copy-to-CSV button, and optional DataTables integration.

Parameters​
container​

HTMLElement

The DOM element to which the table section will be appended.

title​

string

The title to display in the table header.

table​

Object

The table object with a toHTML({ limit }) method for rendering HTML.

index​

number

A unique index used to generate element IDs for the table and its content.

Returns​

void

Example​
renderTable(document.body, 'My Table', myTableObject, 0);

utils.setLoading()​

setLoading: (loading: boolean) => void

Shows or hides the loading overlay and updates the cursor style with state integration.

Parameters​
loading​

boolean

If true, displays the loading overlay and sets the cursor to 'wait'. If false, hides the overlay and resets the cursor.

Returns​

void

utils.setTabButtonsEnabled()​

setTabButtonsEnabled: (enabled: boolean) => void

Enable/disable all non "open file" tab buttons with defensive HTMLElement narrowing.

Parameters​
enabled​

boolean

Returns​

void

utils.showFitData()​

showFitData: (data: Object, filePath?: string, options?: { resetRenderStates?: boolean; updateUI?: boolean; }) => void

Shows FIT data in the UI and updates application state Used by Electron main process to display loaded FIT file data

Parameters​
data​

Object

Parsed FIT file data

filePath?​

string

Path to the FIT file

options?​

Display options

resetRenderStates?​

boolean

Whether to reset rendering states

updateUI?​

boolean

Whether to update UI elements

Returns​

void

Examples​
// Show FIT data with default options
showFitData(parsedData, "/path/to/file.fit");
// Show data without resetting render states
showFitData(parsedData, "/path/to/file.fit", { resetRenderStates: false });

@public

utils.showNotification()​

showNotification: (message: string, type?: "error" | "info" | "success" | "warning", duration?: number, options?: NotificationOptions) => Promise<void>

Notification utilities

Parameters​
message​

string

type?​

"error" | "info" | "success" | "warning"

duration?​

number = null

options?​

NotificationOptions = {}

Returns​

Promise<void>

utils.updateActiveTab()​

updateActiveTab: (tabId: string) => boolean

UI management utilities

Update active tab efficiently

Parameters​
tabId​

string

Returns​

boolean

utils.updateMapTheme()​

updateMapTheme: () => void

Updates the Leaflet map theme based on user's map theme preference Applies dark theme (inversion filter) when user prefers dark maps, regardless of UI theme

Returns​

void

utils.updateTabVisibility()​

updateTabVisibility: (visibleTabId: string | null | undefined) => void

Toggles the visibility of tab content sections by setting the display style. Only the tab content with the specified visibleTabId will be shown; all others will be hidden. If visibleTabId does not match any of the IDs in tabContentIds, no tab content will be displayed.

Parameters​
visibleTabId​

The ID of the tab content element to display. If null or undefined is passed, no tab content will be displayed.

string | null | undefined

Returns​

void

validateAllUtils()​

validateAllUtils: () => ValidationResults

Development helpers

Returns​

ValidationResults

version​

Get Signature​

get version(): string

Metadata with dynamic version getter

Returns​

string