feat!: Use useDecimalInt instead of useDecimalBigInt (#34)

* feat: Add 32- and 64-bit decimal support.

* fix: Fix docs link typo.

* feat!: Change to useDecimalInt flag.

Author: jheer

docs/api/data-types.md

@@ -18,7 +18,7 @@ The table below provides an overview of all data types supported by the Apache A
 |   4 | [Binary](#binary)                   | ✅ | ✅ | ✅ | `Uint8Array` |
 |   5 | [Utf8](#utf8)                       | ✅ | ✅ | ✅ | `string` |
 |   6 | [Bool](#bool)                       | ✅ | ✅ | ✅ | `boolean` |
-|   7 | [Decimal](#decimal)                 | ✅ | ✅ | ✅ | `number`, or `bigint` via the `useDecimalBigInt` flag |
+|   7 | [Decimal](#decimal)                 | ✅ | ✅ | ✅ | `number`, or scaled integers via the `useDecimalInt` flag |
 |   8 | [Date](#date)                       | ✅ | ✅ | ✅ | `number`, or `Date` via the `useDate` flag. |
 |   9 | [Time](#time)                       | ✅ | ✅ | ✅ | `number`, or `bigint` for 64-bit values via the `useBigInt` flag |
 |  10 | [Timestamp](#timestamp)             | ✅ | ✅ | ✅ | `number`, or `Date` via the `useDate` flag. |
@@ -241,7 +241,7 @@ bool()
 
 Create an Decimal data type instance for exact decimal values, represented as a 32, 64, 128, or 256-bit integer value in two's complement. Decimals are fixed point numbers with a set *precision* (total number of decimal digits) and *scale* (number of fractional digits). For example, the number `35.42` can be represented as `3542` with *precision* ≥ 4 and *scale* = 2.
 
-By default, Flechette converts decimals to 64-bit floating point numbers upon extraction (e.g., mapping `3542` back to `35.42`). While useful for many downstream applications, this conversion may be lossy and introduce inaccuracies. Pass the `useDecimalBigInt` extraction option (e.g., to [`tableFromIPC`](/flechette/api/#tableFromIPC) or [`tableFromArrays`](/flechette/api/#tableFromArrays)) to instead extract decimal data as `BigInt` values (64-bit or larger decimals) or integer `number` values (32-bit decimals).
+By default, Flechette converts decimals to 64-bit floating point numbers upon extraction (e.g., mapping `3542` back to `35.42`). While useful for many downstream applications, this conversion may be lossy and introduce inaccuracies. Pass the `useDecimalInt` extraction option (e.g., to [`tableFromIPC`](/flechette/api/#tableFromIPC) or [`tableFromArrays`](/flechette/api/#tableFromArrays)) to instead extract decimal data as `BigInt` values (64-bit or larger decimals) or integer `number` values (32-bit decimals).
 
 * *precision* (`number`): The total number of decimal digits that can be represented.
 * *scale* (`number`): The number of fractional digits, beyond the decimal point.

docs/api/index.md

@@ -23,7 +23,7 @@ Decode [Apache Arrow IPC data](https://arrow.apache.org/docs/format/Columnar.htm
 * *options* (`ExtractionOptions`): Options for controlling how values are transformed when extracted from an Arrow binary representation.
   * *useBigInt* (`boolean`): If true, extract 64-bit integers as JavaScript `BigInt` values. Otherwise, coerce long integers to JavaScript number values (default `false`).
   * *useDate* (`boolean`): If true, extract dates and timestamps as JavaScript `Date` objects. Otherwise, return numerical timestamp values (default `false`).
-  * *useDecimalBigInt* (`boolean`): If true, extract decimal-type data as BigInt values, where fractional digits are scaled to integers. Otherwise, return converted floating-point numbers (default `false`).
+  * *useDecimalInt* (`boolean`): If true, extract decimal-type data as scaled integer values, where fractional digits are scaled to integer positions. Returned integers are `BigInt` values for decimal bit widths of 64 bits or higher and 32-bit integers (as JavaScript `number`) otherwise. If false, decimals are converted to floating-point numbers (default).
   * *useMap* (`boolean`): If true, extract Arrow 'Map' values as JavaScript `Map` instances. Otherwise, return an array of [key, value] pairs compatible with both `Map` and `Object.fromEntries` (default `false`).
   * *useProxy* (`boolean`): If true, extract Arrow 'Struct' values and table row objects using zero-copy proxy objects that extract data from underlying Arrow batches. The proxy objects can improve performance and reduce memory usage, but do not support property enumeration (`Object.keys`, `Object.values`, `Object.entries`) or spreading (`{ ...object }`). Otherwise, use standard JS objects for structs and table rows (default `false`).
 

docs/index.md

@@ -114,11 +114,11 @@ Data extraction can be customized using options provided to table generation met
 
 ```js
 const table = tableFromIPC(ipc, {
-  useDate: true,          // map dates and timestamps to Date objects
-  useDecimalBigInt: true, // use BigInt for decimals, do not coerce to number
-  useBigInt: true,        // use BigInt for 64-bit ints, do not coerce to number
-  useMap: true,           // create Map objects for [key, value] pair lists
-  useProxy: true          // use zero-copy proxies for struct and table row objects
+  useDate: true,       // map dates and timestamps to Date objects
+  useDecimalInt: true, // use scaled ints for decimals, not floating point
+  useBigInt: true,     // use BigInt for 64-bit ints, do not coerce to number
+  useMap: true,        // create Map objects for [key, value] pair lists
+  useProxy: true       // use zero-copy proxies for struct and table row objects
 });
 ```
 

src/batch-type.js

@@ -4,7 +4,7 @@ import { invalidDataType } from './data-types.js';
 
 export function batchType(type, options = {}) {
   const { typeId, bitWidth, precision, unit } = type;
-  const { useBigInt, useDate, useDecimalBigInt, useMap, useProxy } = options;
+  const { useBigInt, useDate, useDecimalInt, useMap, useProxy } = options;
 
   switch (typeId) {
     case Type.Null: return NullBatch;
@@ -30,8 +30,8 @@ export function batchType(type, options = {}) {
       );
     case Type.Decimal:
       return bitWidth === 32
-        ? (useDecimalBigInt ? DirectBatch : Decimal32NumberBatch)
-        : (useDecimalBigInt ? DecimalBigIntBatch : DecimalNumberBatch);
+        ? (useDecimalInt ? DirectBatch : Decimal32NumberBatch)
+        : (useDecimalInt ? DecimalBigIntBatch : DecimalNumberBatch);
     case Type.Interval:
       return unit === IntervalUnit.DAY_TIME ? IntervalDayTimeBatch
         : unit === IntervalUnit.YEAR_MONTH ? DirectBatch

src/build/builder.js

@@ -66,7 +66,7 @@ export function builder(type, ctx = builderContext()) {
       return new BoolBuilder(type, ctx);
     case Type.Decimal:
       return type.bitWidth === 32
-        ? new TransformBuilder(type, ctx, toDecimal32(10 ** type.scale))
+        ? new TransformBuilder(type, ctx, toDecimal32(type.scale))
         : new DecimalBuilder(type, ctx);
     case Type.Date:
       return new TransformBuilder(type, ctx, type.unit ? toBigInt : toDateDay);

src/types.ts

@@ -312,11 +312,13 @@ export interface ExtractionOptions {
    */
   useDate?: boolean;
   /**
-   * If true, extract decimal-type data as BigInt values, where fractional
-   * digits are scaled to integers. Otherwise, return converted floating-point
-   * numbers (default).
+   * If true, extract decimal-type data as scaled integer values, where
+   * fractional digits are scaled to integer positions. Returned integers
+   * are `BigInt` values for decimal bit widths of 64 bits or higher and
+   * 32-bit integers (as JavaScript `number`) otherwise. If false, decimals
+   * are converted to floating-point numbers (default).
    */
-  useDecimalBigInt?: boolean;
+  useDecimalInt?: boolean;
   /**
    * If true, extract 64-bit integers as JavaScript `BigInt` values.
    * Otherwise, coerce long integers to JavaScript number values (default).

test/column-from-array-test.js

@@ -106,7 +106,7 @@ describe('columnFromArray', () => {
     test([0.1000012345678987, -0.1000012345678987], decimal(40, 16, 256));
     test([0.12345678987654321, -0.12345678987654321], decimal(40, 18, 256));
 
-    const opt = { useDecimalBigInt: true };
+    const opt = { useDecimalInt: true };
 
     test([11n, 23n, 34n], decimal(18, 1, 128), opt);
     test([-11n, -23n, -34n], decimal(18, 1, 128), opt);

test/table-from-ipc-test.js

@@ -79,10 +79,10 @@ describe('tableFromIPC', () => {
   it('decodes decimal64 data', () => test(decimal64, Float64Array));
   it('decodes decimal128 data', () => test(decimal128, Float64Array));
   it('decodes decimal256 data', () => test(decimal256, Float64Array));
-  it('decodes decimal32 data to int', () => test(decimal32, Int32Array, { useDecimalBigInt: true }, toDecimalInt));
-  it('decodes decimal64 data to bigint', () => test(decimal64, Array, { useDecimalBigInt: true }, toDecimalBigInt));
-  it('decodes decimal128 data to bigint', () => test(decimal128, Array, { useDecimalBigInt: true }, toDecimalBigInt));
-  it('decodes decimal256 data to bigint', () => test(decimal256, Array, { useDecimalBigInt: true }, toDecimalBigInt));
+  it('decodes decimal32 data to int', () => test(decimal32, Int32Array, { useDecimalInt: true }, toDecimalInt));
+  it('decodes decimal64 data to bigint', () => test(decimal64, Array, { useDecimalInt: true }, toDecimalBigInt));
+  it('decodes decimal128 data to bigint', () => test(decimal128, Array, { useDecimalInt: true }, toDecimalBigInt));
+  it('decodes decimal256 data to bigint', () => test(decimal256, Array, { useDecimalInt: true }, toDecimalBigInt));
 
   it('decodes date day data', () => test(dateDay, Float64Array));
   it('decodes date day data to dates', () => test(dateDay, Array, { useDate: true }, toDate));