Hidden

Overview

Converts an amount to its JSON representation, returning the underlying AmountType object. This is useful for serialization and data transfer.

amount.toJSON();

Features

• Returns the underlying AmountType object for JSON serialization
• Preserves exact internal state with _cents and _currency
• Automatically called by JSON.stringify()
• Useful for API communication and data storage
• Maintains precision with integer cents representation
• Simple and intuitive API
• No side effects - read-only operation
• Comprehensive testing

Arguments

Arg	Type	Default Value	Required
No arguments required

Usage

From an Amount instance, use the toJSON() method to get the JSON representation.

import { amount } from '@inpulse-ui/utils';

const myAmount = amount(123.45, 'USD');
const jsonData = myAmount.toJSON();

console.log(jsonData); // { _cents: 12345, _currency: 'USD' }

Automatic serialization with JSON.stringify():

const price = amount(99.99, 'EUR');
const jsonString = JSON.stringify(price);

console.log(jsonString); // '{"_cents":9999,"_currency":"EUR"}'

Serializing complex objects with amounts:

const order = {
  id: '12345',
  subtotal: amount(85.50, 'USD'),
  tax: amount(6.84, 'USD'),
  total: amount(92.34, 'USD'),
  currency: 'USD'
};

const serialized = JSON.stringify(order);
console.log(serialized);
// '{"id":"12345","subtotal":{"_cents":8550,"_currency":"USD"},"tax":{"_cents":684,"_currency":"USD"},"total":{"_cents":9234,"_currency":"USD"},"currency":"USD"}'

API payload preparation:

const orderAmount = amount(299.99, 'USD');
const shippingAmount = amount(9.95, 'USD');

const apiPayload = {
  order_id: 'ORD-001',
  amounts: {
    subtotal: orderAmount.toJSON(),
    shipping: shippingAmount.toJSON(),
    total: orderAmount.add(shippingAmount).toJSON()
  },
  timestamp: Date.now()
};

console.log(JSON.stringify(apiPayload, null, 2));
// {
//   "order_id": "ORD-001",
//   "amounts": {
//     "subtotal": { "_cents": 29999, "_currency": "USD" },
//     "shipping": { "_cents": 995, "_currency": "USD" },
//     "total": { "_cents": 30994, "_currency": "USD" }
//   },
//   "timestamp": 1697123456789
// }

Database storage and retrieval:

const productPrice = amount(149.95, 'USD');

// Store in database
const productData = {
  name: 'Premium Widget',
  price: productPrice.toJSON(), // { _cents: 14995, _currency: 'USD' }
  category: 'electronics'
};

// Later, reconstruct from stored data
const storedPrice = productData.price;
const reconstructedAmount = new Amount(storedPrice);

console.log(reconstructedAmount.format()); // "$149.95"

Array serialization:

const prices = [
  amount(10.99, 'USD'),
  amount(25.50, 'USD'),
  amount(199.99, 'USD')
];

const serializedPrices = JSON.stringify(prices);
console.log(serializedPrices);
// '[{"_cents":1099,"_currency":"USD"},{"_cents":2550,"_currency":"USD"},{"_cents":19999,"_currency":"USD"}]'

// Deserialize back to Amount instances
const parsed = JSON.parse(serializedPrices);
const reconstructedPrices = parsed.map(data => new Amount(data));

console.log(reconstructedPrices[0].format()); // "$10.99"