coast-utils

Utility functions for browser-focused JavaScript projects, including money formatting and phone number handling.

Installation (bundler / ESM)

npm install coast-utils

Usage

import { formatMoney, formatMoneyJson, displayPhoneNumber, storePhoneNumber } from 'coast-utils';

// Format a single numeric value as currency
const price = formatMoney(123.45, 'USD', 'en-US');
// -> "$123.45"

// Format money values in JSON objects
const data = formatMoneyJson({ amount: 123.45, tax: 10 });
// -> { amount: 123.45, tax: 10, formatted: { amount: "$123.45", tax: "$10.00" } }

// Display phone number in national format
const display = displayPhoneNumber('+12125551234');
// -> "(212) 555-1234"

// Store phone number in E.164 format
const stored = storePhoneNumber('(212) 555-1234');
// -> "+12125551234"

API Reference

formatMoney(value, currency = 'USD', language = 'en-US')

Formats a single numeric value as currency using Intl.NumberFormat.

Parameters:

• value (number): The numeric value to format
• currency (string): ISO 4217 currency code (default: 'USD')
• language (string): BCP 47 language tag (default: 'en-US')

Returns: (string) Formatted currency string

Example:

formatMoney(123.45, 'USD', 'en-US');  // -> "$123.45"
formatMoney(123.45, 'EUR', 'de-DE');  // -> "123,45 €"

formatMoneyJson(data, currency = 'USD', language = 'en-US')

Takes a JSON object or array of objects and adds a formatted property containing money-formatted versions of all numeric values.

Parameters:

• data (object | array): Object or array of objects to process
• currency (string): ISO 4217 currency code (default: 'USD')
• language (string): BCP 47 language tag (default: 'en-US')

Returns: (object | array) Input data with added formatted property

Example:

// Single object
formatMoneyJson({ amount: 123.45, tax: 10 });
// -> { amount: 123.45, tax: 10, formatted: { amount: "$123.45", tax: "$10.00" } }

// Array of objects
formatMoneyJson([{ amount: 50 }, { amount: 75 }]);
// -> [{ amount: 50, formatted: { amount: "$50.00" } }, { amount: 75, formatted: { amount: "$75.00" } }]

displayPhoneNumber(value)

Formats a phone number in national format for display purposes.

Parameters:

• value (string): Phone number in any format (E.164, national, etc.)

Returns: (string) Phone number formatted in national format

Example:

displayPhoneNumber('+12125551234');      // -> "(212) 555-1234"
displayPhoneNumber('2125551234');        // -> "(212) 555-1234"
displayPhoneNumber('(212) 555-1234');    // -> "(212) 555-1234"
displayPhoneNumber('+442071234567');     // -> "020 7123 4567"

storePhoneNumber(value)

Converts a phone number to E.164 format (international standard) for storage.

Parameters:

• value (string): Phone number in any format

Returns: (string) Phone number in E.164 format (e.g., +12125551234)

Example:

storePhoneNumber('(212) 555-1234');  // -> "+12125551234"
storePhoneNumber('2125551234');      // -> "+12125551234"
storePhoneNumber('+12125551234');    // -> "+12125551234"
storePhoneNumber('02071234567');     // -> "+442071234567"

Usage via script tag (browser global)

For direct browser usage without a bundler, use the IIFE build (dist/index.global.js):

<script src="./node_modules/coast-utils/dist/index.global.js"></script>
<script>
  // `CoastUtils` is exposed as a global from the IIFE build
  const formatted = CoastUtils.formatMoney(123.45);
  console.log(formatted);
  // -> "$123.45"
  
  const phone = CoastUtils.displayPhoneNumber('+12125551234');
  console.log(phone);
  // -> "(212) 555-1234"
</script>

Important: Do NOT use dist/index.js or dist/index.cjs directly in browsers - these require a bundler to resolve dependencies. Always use dist/index.global.js for direct browser usage.

Scripts

• build: Bundle the library to dist using tsup.
• dev: Watch and rebuild on changes.
• lint: Run ESLint on source files.
• test: Run unit tests with Vitest.

Releasing / Publishing

1. Update the version in package.json.
2. Run:

npm test
npm run lint
npm run build
npm publish