@half0wl/money

中文文档
1.0.2发布于 2022/12/13MITTypeScriptCommonJS零依赖近 30 天下载 6298

A TypeScript/JavaScript library to make working with monetary values easier and safer.

原始使用文档
文档目录8 节
  1. Installation
  2. Import
  3. Features
  4. Concept
  5. Usage
  6. Development
  7. Acknowledgements
  8. License

💵 money.ts

CI NPM Documentation

This library aims to make working with monetary values in TypeScript/JavaScript safer and easier.

Monetary values always have a currency. They are distinct by currency ($1 is not equivalent to €1), and each currency has different properties that affect how they're displayed, rounded, and parsed. It can be tricky to get all of this right, and if you're handling money at all, it can be expensive to get something wrong!

See: http://martinfowler.com/eaaCatalog/money.html

Installation

# Using npm:
$ npm i @half0wl/money

# Using yarn:
$ yarn add @half0wl/money

Import

// TypeScript
import { Money } from "@half0wl/money"

// JavaScript/CommonJS
'use strict';
const Money = require("@half0wl/money").Money

Features

  • Arithmetic (add, subtract, etc.) and comparison (equals, greater/less than, etc.)
  • Immutability. Every operation returns a new Money object, and properties are not modifiable
  • Locale-aware string formatting
  • Lightweight; zero external dependencies
  • JavaScript is fully supported. Enabling strict mode ('use strict';) is highly recommended, but this will work fine without it
  • Full documentation

Concept

A Money object has a currency and amount, where:

  • Currency is an ISO-4217 alpha code, e.g. USD, JPY, EUR, SGD
  • Amount is represented in the currency's lowest unit, e.g. US$5.00 = 500 cents = { currency: USD, amount: 500 }

Usage

Full API documentation for the Money class is available here.

import { Money } from "@half0wl/money"

/**
 * Basic operations
 */
const listing = new Money('USD', 19999)                // Default constructor from int
listing.getCurrency()                                  // => USD
listing.getAmount()                                    // => 19999
listing.toLocaleString()                               // => '$199.99'

const shipping = Money.fromFloat('USD', 15.00)         // From float
shipping.getAmount()                                   // => 1500
shipping.toLocaleString()                              // => '$15.00'

const xmasDiscount = Money.fromString('USD', '2000')   // From int-string
xmasDiscount.getAmount()                               // => 2000
xmasDiscount.toLocaleString()                          // => '$20.00'

const promoDiscount = Money.fromString('USD', '10.00') // From float-string
promoDiscount.getAmount()                              // => 1000
promoDiscount.toLocaleString()                         // => '$10.00'

const subtotal = listing
  .add(shipping)
  .subtract(xmasDiscount, promoDiscount)
subtotal.getCurrency()                                 // => 'USD'
subtotal.getAmount()                                   // => 18499
subtotal.toLocaleString()                              // => '$184.99'

/**
 * Other arithmetic operations
 */
subtotal.multiply(2.4).toLocaleString()                // => '$443.98'
subtotal.divide(8).toLocaleString()                    // => $23.12

/**
 * Comparisons
 */
promoDiscount.equals(promoDiscount)                    // => false
promoDiscount.greaterThan(promoDiscount)               // => true
shipping.greaterThanOrEqual(listing)                   // => false
shipping.lessThan(listing)                             // => true

/**
 * Formatting
 */
const tenDollars = new Money('USD', 1000)
// Using default locale (`en-US`):
tenDollars.toLocaleString()                            // => $10.00
// Using different locale:
tenDollars.toLocaleString('fr-CA')                     // => 10,00 $ US
// JSON
tenDollars.toJSON()                                    // => {
                                                       //      currency: 'USD',
                                                       //      amount: 1000
                                                       //    }

/**
 * Immutability
 */
// All operations return a new `Money` object:
const sixEur = new Money('EUR', 600)
const oneEur = new Money('EUR', 100)
sixEur.add(oneEur)       // This returns a new Money object!
sixEur.toLocaleString()  // => '€6.00'
                         // The amount value is *not* updated in-place.

// To get the result of `sixEur.add(oneEur)`:
const result = sixEur.add(oneEur)
result.toLocaleString()  // => '€7.00'

// Properties are *always* read-only:
// TypeScript
const twoEur = new Money('EUR', 200)
twoEur['amount'] = 0 // => error TS2540: Cannot assign to 'amount'
                     //    because it is a read-only property.

// JavaScript (in strict mode)
'use strict';
const threeEur = new Money('EUR', 300)
threeEur['amount'] = 0 // => TypeError: Cannot assign to read only
                       //    property 'amount' of object '#<Money>'

Development

Clone the repo and install dependencies:

$ git clone https://github.com/half0wl/money.ts.git
$ yarn install

Tests are located under /tests. To run them:

$ yarn test

Code documentation is written in and generated with TypeDoc. To generate docs:

$ yarn gen-docs

Acknowledgements

License

MIT

版本与发布记录

@half0wl/money 共发布 3 个版本,首次发布于 2022/12/04;过去 12 个月发布了 0 个版本。

版本发布日期距今
1.0.2latest2022/12/133 年前
1.0.12022/12/133 年前
1.0.02022/12/043 年前

关于 @half0wl/money 的常见问题

@half0wl/money 是什么?

A TypeScript/JavaScript library to make working with monetary values easier and safer.

如何安装 @half0wl/money?

在项目目录运行 npm install @half0wl/money,或使用 pnpm add / yarn add / bun add。

@half0wl/money 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@half0wl/money 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@half0wl/money 可以商用吗?

@half0wl/money 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@half0wl/money 的下载量有多少?

根据 npm 官方下载统计,@half0wl/money 在 2026/10/17 – 2026/11/15 这 30 天内被下载 6,298 次,日均约 210 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@half0wl/money 还在维护吗?

最新版本 1.0.2 发布于 2022/12/13(3 年前);至今共发布 3 个版本,其中过去 12 个月发布了 0 个;首次发布于 2022/12/04。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。