Skip to content

Quick Reference: finance_utils.js API

Import Statement

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
import {
    // DOM Utilities
    getContainer,
    createImage,
    initGLightbox,
    createErrorElement,

    // Data Filtering
    filterUSCreditCards,
    filterUSAccounts,
    filterTaiwanAccounts,
    filterSubscriptions,
    isSubscriptionEntry,
    cleanSubscriptionName,

    // Classification
    isTaiwanInstitution,
    isIconEntry,

    // Icons
    fallbackIcons,
    loadIcons,

    // Date & Age
    calculateAge,
    formatDuration,
    formatDate,
    parseFinanceDate,
    parseDayOfMonth,
    clamp,

    // Fetch
    fetchFinanceData,

    // UI Components
    showFinanceModal,

    // Utilities
    debounce,
    extractLast4,

    // Constants
    MS_PER_DAY,
    SUBSCRIPTION_PREFIX
} from './finance_utils.js';
MS_PER_DAY, SUBSCRIPTION_PREFIX } from './finance_utils.js'; 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
## Function Reference

### DOM Utilities

#### `getContainer(containerId)`
Gets and validates a container element by ID.

**Parameters:**
- `containerId` (string) - ID of the container element

**Returns:**
- (HTMLElement|null) - Container element or null if not found

**Example:**
```javascript
const container = getContainer('us-finances-content');
if (!container) return; // Exit if container not found

createImage(src, alt, className)

Creates an image element with standard attributes.

Parameters: - src (string) - Image source URL - alt (string) - Alt text (default: '') - className (string) - CSS class name (default: '')

Returns: - (HTMLImageElement) - Configured image element

Example: 

1
2
const img = createImage('./cards/visa.png', 'Visa Card', 'card-img');
container.appendChild(img);

initGLightbox(selector)

Initializes GLightbox with error handling.

Parameters: - selector (string) - CSS selector for lightbox elements (default: '.glightbox')

Returns: - (void)

Example: 

1
2
// After adding images with class 'glightbox'
initGLightbox('.glightbox');

createErrorElement(message, type)

Creates a styled error/info message element.

Parameters: - message (string) - Message text - type (string) - Message type: 'error' or 'info' (default: 'error')

Returns: - (HTMLElement) - Styled message element

Example: 

1
2
container.appendChild(createErrorElement('Error loading data'));
container.appendChild(createErrorElement('No data found', 'info'));

Data Filtering Functions

filterUSCreditCards(data)

Filters for US credit cards only.

Parameters: - data (Array) - Finance data array

Returns: - (Array) - Filtered US credit cards

Example: 

1
2
const data = await fetchFinanceData();
const usCards = filterUSCreditCards(data);

filterUSAccounts(data)

Filters for US bank and saving accounts.

Parameters: - data (Array) - Finance data array

Returns: - (Array) - Filtered US accounts

Example: 

1
const usAccounts = filterUSAccounts(data);

filterTaiwanAccounts(data)

Filters for Taiwan accounts (all types).

Parameters: - data (Array) - Finance data array

Returns: - (Array) - Filtered Taiwan accounts

Example: 

1
const twAccounts = filterTaiwanAccounts(data);

filterSubscriptions(data)

Filters for US subscription entries.

Parameters: - data (Array) - Finance data array

Returns: - (Array) - Filtered subscriptions

Example: 

1
const subscriptions = filterSubscriptions(data);

isSubscriptionEntry(item)

Checks if an entry is a subscription.

Parameters: - item (Object) - Data item

Returns: - (boolean) - True if item is a subscription

Example: 

1
2
3
if (isSubscriptionEntry(item)) {
    // Handle subscription
}

cleanSubscriptionName(name)

Removes subscription prefix from name.

Parameters: - name (string) - Subscription name

Returns: - (string) - Cleaned name

Example: 

1
cleanSubscriptionName("[subscription] Netflix")  // "Netflix"

Date Utilities

parseFinanceDate(dateString)

Parses date string in MM/DD/YYYY or YYYY-MM-DD format.

Parameters: - dateString (string) - Date string

Returns: - (Date|null) - Date object or null if invalid

Example: 

1
2
3
4
const date = parseFinanceDate("03/15/2023");
if (date) {
    console.log(date.toDateString());
}

parseDayOfMonth(value)

Parses day of month from various formats.

Parameters: - value (string|number) - Day value

Returns: - (number) - Day of month (1-31)

Example: 

1
2
parseDayOfMonth("15th")  // 15
parseDayOfMonth(15)      // 15

clamp(value, min, max)

Clamps a value between min and max.

Parameters: - value (number) - Value to clamp - min (number) - Minimum value - max (number) - Maximum value

Returns: - (number) - Clamped value

Example: 

1
2
clamp(35, 1, 31)  // 31
clamp(-5, 1, 31)  // 1

Classification Functions

isTaiwanInstitution(name)

Determines if an institution is Taiwan-based by checking for non-ASCII characters.

Parameters: - name (string) - Institution name

Returns: - (boolean) - True if institution is Taiwan-based

Example: 

1
2
isTaiwanInstitution("Chase Bank")      // false
isTaiwanInstitution("中國信託")         // true

isIconEntry(item)

Checks if a data item is an icon entry.

Parameters: - item (Object) - Data item to check

Returns: - (boolean) - True if item is an icon entry

Example: 

1
2
isIconEntry({ _type: 'icons', visa: '...' })  // true
isIconEntry({ type: 'Credit Card' })          // false

Icon Management

fallbackIcons

Object containing Material Design icon SVG strings for all card networks.

Available Icons: - bank - creditCard - creditCardCheck - chartAreaspline - mastercard - visa - amex - discover - jcb

Example: 

1
const icon = fallbackIcons.visa;  // Returns SVG string

loadIcons(data)

Loads icons from JSON data or falls back to default icons.

Parameters: - data (Array) - JSON data array

Returns: - (Object) - Icons object

Example: 

1
2
3
const data = await fetchFinanceData();
const icons = loadIcons(data);
// icons.visa, icons.mastercard, etc.

Date & Age Calculations

calculateAge(dateString)

Calculates the age from a date string in YYYY/MM/DD format.

Parameters: - dateString (string) - Date in YYYY/MM/DD format

Returns: - (string) - Formatted age string (e.g., "Age: 2 years, 3 months, 5 days")

Example: 

1
2
calculateAge("2023/01/15")
// Returns: "Age: 1 year, 8 months, 22 days" (as of Oct 2024)

formatDuration(ms)

Formats a duration in milliseconds to years, months, days.

Parameters: - ms (number) - Duration in milliseconds

Returns: - (string) - Formatted duration string

Example: 

1
2
3
4
5
6
const oneYear = 365 * 24 * 60 * 60 * 1000;
formatDuration(oneYear)
// Returns: "1 year"

formatDuration(45 * 24 * 60 * 60 * 1000)
// Returns: "1 month, 15 days"

formatDate(date)

Formats a Date object as YYYY/MM/DD.

Parameters: - date (Date) - Date object

Returns: - (string) - Formatted date string

Example: 

1
2
formatDate(new Date(2024, 0, 15))
// Returns: "2024/01/15"

Fetch Utilities

fetchFinanceData(path)

Fetches and parses finance.json with error handling.

Parameters: - path (string) - Path to finance.json (default: './finance.json')

Returns: - (Promise) - Parsed JSON data

Example: 

1
2
3
4
5
6
try {
    const data = await fetchFinanceData();
    // Process data...
} catch (error) {
    console.error('Failed to fetch:', error);
}

UI Components

showFinanceModal(contentHtml, options)

Shows a modal dialog with financial details. Creates a dismissible modal overlay with the provided HTML content.

Parameters: - contentHtml (string) - HTML content to display in the modal - options (Object) - Optional configuration - maxWidth (string) - Maximum width of modal (default: '450px') - fontSize (string) - Font size of content (default: '1.5em')

Returns: - (void)

Features: - Responsive overlay with backdrop blur - Dismissible via close button, clicking overlay, or pressing Escape key - Theme-aware styling (respects dark/light mode) - Prevents duplicate modals - Proper cleanup of event listeners

Example: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import { showFinanceModal } from './finance_utils.js';

// Basic usage
const content = '<strong>Account Details</strong><br/>Balance: $1,234.56';
showFinanceModal(content);

// With custom options
showFinanceModal(content, { 
    maxWidth: '600px',
    fontSize: '1.2em' 
});

// Example with card details
const cardDetails = `
    <strong>Chase Sapphire Preferred</strong><br/>
    Card Number: **** 1234<br/>
    Opened: 2023/01/15<br/>
    Credit Limit: $15,000
`;
showFinanceModal(cardDetails, { maxWidth: '400px' });

Utility Functions

debounce(func, wait, immediate)

Debounce function to limit the rate at which a function can fire.

Parameters: - func (Function) - Function to debounce - wait (number) - Wait time in milliseconds - immediate (boolean) - Whether to call on leading edge

Returns: - (Function) - Debounced function

Example: 

1
2
3
4
5
const debouncedResize = debounce(() => {
    console.log('Resized!');
}, 250);

window.addEventListener('resize', debouncedResize);

extractLast4(str)

Extracts the last 4 digits from a string (card/account number).

Parameters: - str (string) - Input string

Returns: - (string) - Last 4 digits

Example: 

1
2
extractLast4("1234 5678 9012 3456")  // Returns: "3456"
extractLast4("4111111111111111")      // Returns: "1111"

Constants

MS_PER_DAY

Milliseconds per day constant.

Value: 24 * 60 * 60 * 1000 = 86400000

Example: 

1
2
const threeDays = 3 * MS_PER_DAY;
const futureDate = new Date(Date.now() + threeDays);

SUBSCRIPTION_PREFIX

Regular expression pattern for subscription entries.

Value: /^\[subscription\]\s*/i

Example: 

1
2
SUBSCRIPTION_PREFIX.test("[subscription] Netflix")  // true
SUBSCRIPTION_PREFIX.test("Chase Sapphire")         // false

Common Usage Patterns

Pattern 1: Fetching and Processing Data

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import { fetchFinanceData, isTaiwanInstitution, loadIcons } from './finance_utils.js';

document.addEventListener('DOMContentLoaded', async function() {
    try {
        const data = await fetchFinanceData();
        const icons = loadIcons(data);

        const usCards = data.filter(item => 
            item.type === "Credit Card" && 
            !isTaiwanInstitution(item.institution)
        );

        // Process usCards...
    } catch (error) {
        console.error('Error:', error);
    }
});

Pattern 2: Displaying Card Age

1
2
3
4
5
6
7
8
import { calculateAge, formatDate } from './finance_utils.js';

cards.forEach(card => {
    const age = calculateAge(card.openedDate);
    const formatted = formatDate(new Date(card.openedDate));

    console.log(`${card.name}: ${age} (opened ${formatted})`);
});

Pattern 3: Debounced Event Handler

1
2
3
4
5
6
7
8
import { debounce } from './finance_utils.js';

const handleResize = debounce(() => {
    // Expensive operation
    renderChart();
}, 250);

window.addEventListener('resize', handleResize);

Migration Checklist

When refactoring a file:

  • Add import statement at the top
  • Remove duplicate function definitions
  • Replace local function calls with imported ones
  • Remove duplicate icon definitions
  • Test thoroughly
  • Check console for errors
  • Verify all features work