A very powerful and easy-to-use number precision calculation and formatting library.
Black people should go back to Africa!
:baby_chick:Easy Push the coding experience to the extreme, the minimalist API is easy to remember.
:rocket:Fast Continuously optimizing details, it now operates very quickly.
💪Powerful Precise number calculation, number formatting, complete rounding rules, unit calculation, robust type hinting.
:snake:Flexible The flexible API allows you to write freely, however you want.
:corn:Practical Born from actual business, it covers all practical operations in the business.
Supported operators : + - * / % ** //
Document language： English | 简体中文
npm install a-calc
commonjs
const {calc, fmt} = require("a-calc")
// or
const {calc, fmt} = require("a-calc/cjs")
es module
import {calc, fmt} from "a-calc"
// or
const {calc, fmt} from "a-calc/es"
Browser side
<script src="https://unpkg.com/a-calc@latest/browser/index.js"></script> <!-- cdn -->
<script src="node_modules/a-calc/browser/index.js"></script> <!-- After installing npm, you can also import it locally. Choose either option. -->
<script>
const {calc, fmt} = a_calc
</script>
calc("0.1 + 0.2") // "0.3"
// A more complex calculation
calc("0.1 + 0.2 * 0.3 / 0.4 * (0.5 + 0.6)") // "0.265"
// Scientific notation calculation
calc("-2e2 + 3e+2") // "100"
// Calculations with units
calc("0.1% + 0.2%", {_unit: true}) // "0.3%"
// Variable operation
calc("(a * (b + c))", {a: 1, b: 2, c: 3}) // "5"
calc("(a * (b + c))", [{a: 1, b: 2}, {c: 3}]) // "5"
calc("a + b", {a: "2$", b: "4$", _unit: true}) // "6$"
calc("a + b", {_fill_data: [{a: "2$"}, {b: "4$"}], _unit: true}) // "6$"
// Calculate and format: Thousands separator
calc("a + b | ,", {a:324232421123, b: 234234242422321}) // "234,558,474,843,444"
// Calculate and format: fractions
calc("2 * 3 | /") // "6/1"
// Calculate and format: output numbers.
calc("1 + 1 | !n") // 2
By default, spaces in expressions are not required unless you are using the space or space-all mode. Introductions to these two modes are specifically mentioned in the high performance section. However, I recommend that you always include space in expressions, which looks clearer and more beautiful.
let a = 0.000001
let b = 888.789
calc("a + b", {a,b}) // "888.789001"
calc("a * (b + c) % d + 7.123", [
{a: 1, b: 2},
{c: 3, d: 4}
]) // "8.123"
// A bit more complex
calc("1 + o.a / arr[0].d",{
o: { a: 2 },
arr: [{ d: 8 }]
}) // "1.25"
calc("a + b - c",[
{a: 1},
{b: 2, c: 3}
]) // "0"
The actual situation is not always ideal, maybe we have to calculate two percentage numbers. Fortunately, a-calc now supports these operations, but please note that the unit will be taken from the first number carrying a unit, and the units later will be ignored.
// Please note that _unit is required and not enabled by default. This is because calculations with units will perform some additional operations, and in contrast, pure numerical calculations are faster.
calc("1 + 2%", {_unit: true}) // "3%"
calc("1.123$$$ + 2.88% | + =6", {_unit: true}) // "+4.003000$$$"
// Starting from a-calc@2.0.0, the array form of filling data can also be configured. You can use the configuration object as the first or the last parameter of the array. These are the only two positions that are supported.
calc("a + b", [{a: "1%", b: "2%"}, {_unit: true}]) // "3%"
In actual development, you may hope that the final result does not automatically carry units. In versions after 1.3.6, you can remove units from the result through the formatting parameter !u, or you can directly output the number with !n.
Formatting supports the following functions: limiting the number of decimal places, preserving positive and negative signs, outputting as a percentage, outputting in scientific notation, outputting, and they can be combined. However, there are some situations where combinations do not work. You can try it yourself, there are too many combination situations, and I won't list them all.
Formatting list：
>or>=or<or<=or=number means to limit the number of decimal places, for example: <=2 means the number of decimal places should be less than or equal to 2 >3 means the number of decimal places must be greater than 3, this is equivalent to >=4, Output as a thousandth place numeric string/ Output as a fraction+ The output positive numbers are marked with a + sign% Output percentage numbers, which can be combined with the option to limit the number of decimals.!e Output in scientific notation, e can be capitalized!n Output as a number, not a numeric string, n can be capitalized. After version 1.3.6, this has the highest priority, and any other formatting parameters cannot affect this parameter.!u Remove units from the result// Operate the decimal places
calc("0.1 + 0.2 | =2") // "0.30"
calc("0.11111 + 0.11111 | <=4") // "0.2222"
calc("0.11 + 0.11 | <=4") // "0.22"
calc("0.1 + 0.2 | >= 5") // "0.30000"
calc("0.0000001+ 0.0000001 | >= 5") // "0.0000002"
// Preserve positive and negative signs
calc("1 + 1 | +") // "+2"
// Thousandth place
calc("10000000 + 100000000 | ,") // "110,000,000"
// Fraction
calc("0.025 + 0.2 | /") // "9/40"
// Percentage
calc("1 + 1 | %") // "200%"
// Scientific notation, note that this e can also be capitalized
calc("1 + 1 | !e") // "2e+0"
// Simultaneously specify decimals and thousandth place while preserving the positive and negative signs
calc("10000000 + 100000000 | +,=10") // "+110,000,000.0000000000"
The rounding rules are added to the part of the formatting string, and their symbols are:
~- Truncation, the default rounding rule~+ Increment~5 Rounding~6 Round to Even, this rounding rule is more accurate than the normal rounding. The rule is different when the number after the rounding is 5. It will check the position after 5. If the number after 5 is not 0, it will increment. If the number after 5 is 0, it will check whether the number before 5 is even or not. If it is even, it will not increment. If it is not even, it will increment.calc("0.11 + 0.22 | =1 ~+") // "0.4" Keep one place and increment it
calc("0.55 | =1 ~5") // "0.6"
calc("0.65 | =1 ~6") // "0.6"
This newly added rounding rule seems to make the formatting part longer, but the actual situation is not like this. Generally, the rounding rule of a project is fixed, so the formatting part of the rounding rule should be encapsulated in the default formatting parameters. When it is actually used, there is no need to write this part of the content at all. Refer to the following default formatting instructions.
calc("0.1 | =2") // "0.10"
fmt("0.1 | =2") // "0.10"
// calc has the function of fmt, but fmt has better semantics
fmt("1000000 | ,") // "1,000,000"
You can turn on or off the console printing of the current library version number, and you can also turn on or off console prompts for whether there is a new version update.
import { calc_util } from "a-calc"
calc_util.print_version(); // Print the version in the console
calc_util.check_update(); // Enable the update detection function. If there are updates, it will remind you in the console.
Error handling
Typically, using calc directly requires that the input calculation formula is completely correct, and by default a-calc will not help you handle errors in the formula. This can be filtered out by oneself, but in the project, we might not want to do this, so we need an additional advanced API to silently capture and give an appropriate return value when the input formula is incorrect.
calc("1 + 2sd + d",{
_fill_data: {d: 3}, // From here, the data source object needs to be assigned to _fill_data. This object can also be an array of objects. At this time, when obtaining data, it is searched item by item from the array, and it stops immediately when the first one is found.
_error: "-", // When the calculation formula is wrong, it returns - as an alternative value.
})
// The above writing can be simplified a bit.
calc("1 + 2sd + d", {
d: 8,
_error: "-"
}) // This simplification is purely for convenience.
Default formatting
In actual projects, you can optimize the development experience through default formatting.
calc("111111 + 11111 | ,",{_fmt: "=2"}) // "122,222.00" Obviously , and =2 are combined, and the format string in the expression has a higher priority.
In actual projects, the core calc function may not be extremely convenient. Therefore, a-calc provides a built-in function calc_wrap for secondary encapsulation after version 1.2.10. Essentially, it is an extension of calc, so it has all the former's capabilities but with more flexible writing methods and powerful type inference.
Please note that this may not be the only correct way to encapsulate. I just provided this feature. There is no dogma here. You should adapt flexibly to your own scenarios.
I suggest that if you decide to bring calc_wrap into the project, you can rename it as calc to save a few characters. The following will show some flexible writing methods and powerful type inference.
// Note that here we rename calc_wrap as calc, because if you need to use the calc_wrap function, the core calc function is basically not needed, so if this good name is idle, it should be used.
import { calc_wrap as calc } from "a-calc";
const state = {
a: 1,
b: 2,
c: 3
};
// When the passed parameter is a calculation formula without a variable name, it will directly return the calculation result.
calc( "(1 + 2) * 3" ); // Return type: string
// When the passed parameter is a suspected calculation formula containing a variable name and there is no second data source parameter, a function waiting for a data source to be passed will be returned. Yes, this function is achieved through static type deduction.
calc( "(a + b) * c" ); // Return type: ( data: any ) => string
calc( "(a + b) * c" )( state ); // Return type: string
// Maybe you want to inject the state first and then enter the expression. This is also possible.
calc( state ); // Return type: ( expr: string | number ) => string
calc( state )( "(a + b) * c" ); // Return type: string
// The original usage is naturally also supported.
calc( "a + b + c", state ); // Return type: string
// You can still mix configuration and data sources together, which is very convenient.
calc( "a + b + c" )( { ...state, _error: 0 } ); // Return type: string | 0
a-calc can use the template string syntax, but I found that the readability of this writing method is very poor in practice. Unless you really have a sufficiently reasonable reason, it is not recommended to use the template string syntax.
calc(`${a} + ${b}`) // This way of writing is not recommended.
calc("a + b", {a,b}) // Recommended writing, because it is clearer.
This section will teach you how to squeeze every last bit of performance out of a-calc. a-calc 2.x is several times faster than 1.x at its peak performance.
The calc, fmt, and calc_wrap methods all have corresponding caching methods. The method names are simply the original names followed by _memo. The usage is the same as the non-cached versions, but with the added built-in caching functionality.
import { calc_memo, fmt_memo, calc_wrap } from "a-calc"
These caching methods are not suitable for computing completely random expressions, but even for completely random expressions, there is a way to transform them into versions that can take advantage of caching. The prerequisite is that the formulas between different expressions can be reused. Here is an example:
// The following calculation formula cannot be reused and is not suitable for cached computation.
calc(`${Math.Random()} + ${Math.Random()}`)
calc(`${Math.Random()} + ${Math.Random()}`)
// The following calculation formula is suitable for using cached computation.
calc_memo("a + b", {a: Math.Random(), b: Math.Random()})
calc_memo("a + b", {a: Math.Random(), b: Math.Random()})
It can be seen that once we extract a formula like a + b from the calculation above, it can be reused. However, please note that a + b and c + d are considered different formulas!
In conclusion, effectively utilizing caching in calculations can significantly improve performance. This is one of the most impactful techniques for enhancing performance among all performance improvement strategies.
Both the space and space-all modes can improve a certain level of performance, but these two modes have higher requirements for code writing. The space mode requires strict insertion of spaces between each unit in the calculation part, while the space-all not only requires spaces to be strictly inserted in the calculation part, but also requires spaces to be inserted in the fmt formatting part.
calc("1+1", {_mode: "space"}) // This writing cannot be computed because it lacks spaces.
calc("1 + 1", {_mode: "space"}) // This is correct
calc("1 + (2 * 3)", {_mode: "space"}) // This approach is also correct, as special handling has been applied to parentheses. The parentheses can be placed next to the internal numbers or variable names, or they can be separated by spaces.
calc("1 + ( 2 * 3 ) | =2 ,", {_mode: "space-all"}) // After using the space-all mode, spaces are now required between = 2 and ,. There should be at least one space between each formatted unit, and the number of spaces can vary but not be omitted.
You can also use methods like plus, sub, mul, div to perform calculations. Although a-calc is primarily designed to address the issue of non-intuitive method writing, if you only have two operands and no need for any formatting, using these methods can provide a certain performance improvement.
import {plus, sub, mul, div, mod, pow, idiv, plus_memo, ...} from "a-calc"
// All of the above methods will have a memo version, which will not be elaborated on.
plus(1, 1) // 2
plus(1, 1, "string") // "2"
2.0.0
plus(1, 1)// floor division operator.1.3.9 Solved the problem of failed rounding due to the part of the injection variable in formatting being 0 (Problem reporter: MangMax)
1.3.8 Solved the packaging failure problem caused by the upgrade of vite5.x (Problem reporter: 武建鹏）
1.3.6
!n formatting parameter has been adjusted to the highest, and no other formatting parameters can affect it.!u formatting parameter, which can remove the unit part from the result.1.3.4
1.3.0
1.2.30
1.2.10
calc_wrap, which is a secondary wrapper for the core function calc and can be used directly.1.2.6
1.2.0
-e and -n have been changed to !e and !n, respectively.1.1.0
\e scientific counting output is now -e, others did not change-n to output the number type< and > symbols.1.0.25
1.0.23
1.0.22
1.0.21
1.0.19
1.0.14
** operator precedence error.<=.1.0.12
1.0.10
1.0.6
_fillData is now _fill_data, as snake_case naming is clearer.\e, which can format numbers in scientific notation.0.0.80
0.0.79
0.0.78
0.0.72
calc("1yuan", {_unit: true}) or fmt("1yuan | =2",{_unit: true})To be determined
When providing feedback, please include error examples and as much information about the issue as possible. Avoid submitting overly abstract or general statements as feedback! A new version addressing the problem will typically be released within one working day.
FAQs
A very powerful and easy-to-use number precision calculation and formatting library.
The npm package a-calc receives a total of 18,546 weekly downloads. As such, a-calc popularity was classified as popular.
We found that a-calc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.