Type alias DBNumberConfig

NoSQL database allows you to store arbitrary precision decimal numbers in tables by using database type Number, which supports all numbers represented by Java BigDecimal class. By default, the driver represents them as Javascript numbers. However this has some limitations:

• The number of significant digits is limited to what can be represented by Javascript number type, which is approximately 15 decimal digits, so the values with higher precision cannot be reresented exactly and will be rounded.
• The range is limited to what can be represented by Javascript numbers, which is upproximately up to +-1e308.
• Javascript numbers are stored in binary and not decimal format, which means that some decimal values cannot be represented exactly and are subject to rounding errors when performing decimal calculations.

Because Javascript and Node.js do not currently have a standard way to represent arbitrary precision decimal numbers, the driver allows you to use a 3rd party number library of your choice. Typically the number libraries represent numbers as objects of certain prototype or class and have methods to perform arithmetic and other operations. If you enable this feature, the driver will represent the column values of datatype Number as objects of this type from the number library. You can pass these objects as record fields for put operations, as key fields for get operations and they will also be returned as part of get and query results wherever the column value or expression result is of datatype Number. Then your application can use methods from the number library to perform further numeric operations on number objects or convert them to suitable display representation.

In most cases you only need the following:

1. Install the 3rd party number library of your choice (typically from NPM) globally or as a dependency of your application (note that the driver does not automatically install number libraries)
2. In the initial Config used to create NoSQLClient, specify dbNumber property as dbNumber: 'module_name' where module_name is the module name of the number library

See examples below.

The above is sufficient for most cases when using default settings and for number libraries that provide standard method names for common operations. The driver has been tested with the following number libraries:

• decimal.js
• decimal.js-light
• bignumber.js
• big.js

These libraries should work out of the box with simple steps as described above. However you may use any number library of your choice as long as it uses objects to represent arbitrary precision decimal numbers, provides constructor function to create these objects and supports some common operations. Below we describe what the driver needs to know from the number library and whether it will work out of the box as mentioned above or if it may require additional configuration.

The driver needs to know the following:

1. Constructor function. The constructor should be able to create the number object from its string representation. Typically the number libraries export the constructor as a sole module export, so that the result of require('module_name') is the constructor. In this case no additional configuration is required.
2. Conversion to string. Typically this is the instance method toString (overriden from Object class), in which case no additional configuration is required.
3. Operations for comparison, addition, subtraction, multiplication and division, as may be needed by the driver for client-side query processing. These are typically static (properties of the constructor itself) and/or instance methods (properties of constructor's prototype), with the static methods taking 2 arguments and instance methods taking one argument. The driver will look for common method names (instance or static) such as "add", "plus" for addition, "subtract", "sub", "minus" for subtraction, etc. See NumberLibMethods for complete list of names. If the number library of your choice uses any of the common names for each operation listed above, no additional configuration is required.
4. Precision and rounding mode. These are optional and if not specified, default values will be used. On the server side, NoSQL database uses Java BigDecimal to do calculations for Number datatype during query processing. The result of each operation is rounded accoring to Java MathContext settings, which consist of precision (number of significant digits) and rounding mode (how to round the result to precision), so these settings need to be provided to the server for query processing. You may choose to provide them explicitly in configuration (see NumberLibConfig) or let the driver figure them out from the number library settings using some common property names (see NumberLibPrecision and NumberLibRoundingMode). If not found, default precision of 20 and rounding mode ROUND_HALF_UP will be used.

Note that configuration for this feature is always specified as dbNumber property of Config and thus can be provided either as part of Config Javascript object or in JSON file containing Config.

dbNumber property can be one of the following:

• String specifying number library module name as discussed above.
• Constructor function (not available if using JSON file). You may specify constructor function explicitly. This is useful when you want to set custom settings for the constructor (to customize created number instances) before passing it to the driver instead of using default number library settings. Also see Constructor.
• NumberLibConfig object if more complex configuration is desired.