feat(NODE-6087): add Int32.fromString method (#670)

src/int_32.ts

@@ -1,4 +1,6 @@
 import { BSONValue } from './bson_value';
+import { BSON_INT32_MAX, BSON_INT32_MIN } from './constants';
+import { BSONError } from './error';
 import type { EJSONOptions } from './extended_json';
 import { type InspectFn, defaultInspect } from './parser/utils';
 
@@ -32,6 +34,41 @@ export class Int32 extends BSONValue {
     this.value = +value | 0;
   }
 
+  /**
+   * Attempt to create an Int32 type from string.
+   *
+   * This method will throw a BSONError on any string input that is not representable as an Int32.
+   * Notably, this method will also throw on the following string formats:
+   * - Strings in non-decimal formats (exponent notation, binary, hex, or octal digits)
+   * - Strings non-numeric and non-leading sign characters (ex: '2.0', '24,000')
+   * - Strings with leading and/or trailing whitespace
+   *
+   * Strings with leading zeros, however, are allowed.
+   *
+   * @param value - the string we want to represent as an int32.
+   */
+  static fromString(value: string): Int32 {
+    const cleanedValue = !/[^0]+/.test(value)
+      ? value.replace(/^0+/, '0') // all zeros case
+      : value[0] === '-'
+        ? value.replace(/^-0+/, '-') // negative number with leading zeros
+        : value.replace(/^\+?0+/, ''); // positive number with leading zeros
+
+    const coercedValue = Number(value);
+
+    if (BSON_INT32_MAX < coercedValue) {
+      throw new BSONError(`Input: '${value}' is larger than the maximum value for Int32`);
+    } else if (BSON_INT32_MIN > coercedValue) {
+      throw new BSONError(`Input: '${value}' is smaller than the minimum value for Int32`);
+    } else if (!Number.isSafeInteger(coercedValue)) {
+      throw new BSONError(`Input: '${value}' is not a safe integer`);
+    } else if (coercedValue.toString() !== cleanedValue) {
+      // catch all case
+      throw new BSONError(`Input: '${value}' is not a valid Int32 string`);
+    }
+    return new Int32(coercedValue);
+  }
+
   /**
    * Access the number value.
    *

test/node/int_32_tests.js

@@ -2,6 +2,7 @@
 
 const BSON = require('../register-bson');
 const Int32 = BSON.Int32;
+const BSONError = BSON.BSONError;
 
 describe('Int32', function () {
   context('Constructor', function () {
@@ -97,4 +98,50 @@ describe('Int32', function () {
       });
     }
   });
+
+  describe('fromString', () => {
+    const acceptedInputs = [
+      ['Int32.max', '2147483647', 2147483647],
+      ['Int32.min', '-2147483648', -2147483648],
+      ['zero', '0', 0],
+      ['a string with non-leading consecutive zeros', '45000000', 45000000],
+      ['a string with zero with leading zeros', '000000', 0],
+      ['a string with positive leading zeros', '000000867', 867],
+      ['a string with explicity positive leading zeros', '+000000867', 867],
+      ['a string with negative leading zeros', '-00007', -7]
+    ];
+    const errorInputs = [
+      ['Int32.max + 1', '2147483648', 'larger than the maximum value for Int32'],
+      ['Int32.min - 1', '-2147483649', 'smaller than the minimum value for Int32'],
+      ['positive integer with decimal', '2.0', 'not a valid Int32 string'],
+      ['zero with decimals', '0.0', 'not a valid Int32 string'],
+      ['negative zero', '-0', 'not a valid Int32 string'],
+      ['Infinity', 'Infinity', 'larger than the maximum value for Int32'],
+      ['-Infinity', '-Infinity', 'smaller than the minimum value for Int32'],
+      ['NaN', 'NaN', 'not a safe integer'],
+      ['a fraction', '2/3', 'not a safe integer'],
+      ['a string containing commas', '34,450', 'not a safe integer'],
+      ['a string in exponentiation notation', '1e1', 'not a valid Int32 string'],
+      ['a octal string', '0o1', 'not a valid Int32 string'],
+      ['a binary string', '0b1', 'not a valid Int32 string'],
+      ['a hexadecimal string', '0x1', 'not a valid Int32 string'],
+      ['a empty string', '', 'not a valid Int32 string'],
+      ['a leading and trailing whitespace', '    89   ', 'not a valid Int32 string']
+    ];
+
+    for (const [testName, value, expectedInt32] of acceptedInputs) {
+      context(`when the input is ${testName}`, () => {
+        it(`should successfully return an Int32 representation`, () => {
+          expect(Int32.fromString(value).value).to.equal(expectedInt32);
+        });
+      });
+    }
+    for (const [testName, value, expectedErrMsg] of errorInputs) {
+      context(`when the input is ${testName}`, () => {
+        it(`should throw an error containing '${expectedErrMsg}'`, () => {
+          expect(() => Int32.fromString(value)).to.throw(BSONError, expectedErrMsg);
+        });
+      });
+    }
+  });
 });