Enjoy Rich Integral Types of .NET and Overcome the 53-bit Limitation of JavaScript

• JsLargeIntegralDemo at GitHub

Introduction

This article is the sequel of Dealing with large integral numbers in JavaScript for integral types of ASP.NET Core Web API which illustrates some by-design nature of JavaScript when dealing with large integral numbers and suggests some solutions. Please read the first one before reading this one.

This article introduces a systematic approach for utilizing integral types of .NET in JavaScript clients.

1. JS Doc comment hinting the data range of a property of a TypeScript interface or function parameter. For example, for .NET byte, the document will be Type: byte -128 to 127. And such doc comment will be generated under some conditions.
2. On the JavaScript client end, use string object for 54-bit and greater in the request payload and the response payload. Such mapping will be generated.
3. On the ASP.NET Core Web API end, customize the serialization / binding for Int64, UInt64 and BigInteger.
4. For Angular clients with Reactive Forms, the form codes provide validators to enforce the data constraints as declared on the service side. Such validation can be generated.

Using the Code

Clone or fork JsLargeIntegralDemo at GitHub to get a local working copy.

Prerequisites

• .NET 7/8
• Visual Studio 2022
• NuGet package: Fonlow.IntegralExtensions
• NuGet packages of WebApiClientGen

Steps

1. Stay with the master branch or tag v1.
2. Build the sln.
3. Run IntegrationTestsCore in Test Explorer or "DotNet Test". The test suite will launch Web API DemoCoreWeb and then close after finishing running the test cases. This is to verify that the Web service is functioning well.
4. Run StartDemoCoreWeb.ps1 to launch the Web API DemoCoreWeb.

Folder HeroesDemo contains a modified "Tour of Heroes", an Angular app talking to DemoCoreWeb. After installing packages through running npm install, you run ng test, then you will see:

Comparing with the code example in article "Dealing with large integral numbers in JavaScript for integral types of ASP.NET Core Web API", this one diffs by:

1. Customized data binding for Int64, UInt64 and BigInteger.
2. JavaScript test suite "Numbers API" adapting the serialization at the service side.

In service start-up codes with IServiceCollection, the following JSON converters are injected:

.AddNewtonsoftJson(
    options =>
    {
        options.SerializerSettings.Converters.Add(new Int64JsonConverter());
        options.SerializerSettings.Converters.Add(new Int64NullableJsonConverter());
        options.SerializerSettings.Converters.Add(new UInt64JsonConverter());
        options.SerializerSettings.Converters.Add(new UInt64NullableJsonConverter());
        options.SerializerSettings.Converters.Add(new BigIntegerJsonConverter());
        options.SerializerSettings.Converters.Add(new BigIntegerNullableJsonConverter());
    }
);

These converters are imported from NuGet package: Fonlow.IntegralExtensions .

Hints

• The C# client API and the C# integration test suite IntegrationTestsCore remains the same, and the results remain the same while the service has altered the way of serialization for Int64, UInt64 and BigInteger, since the System.Net.Http.HttpClient is handling well both ways of serialization: JSON number object or JSON string object.

Integration Tests with JavaScript / TypeScript Clients

This test suite uses string for integral numbers of 64-bit, 128-bit and BigInt when talking to ASP.NET Core Web API which provides decent Web API data binding upon JSON number object and JSON string object that represent a number.

Remarks

• You should find out if your backend developed on PHP, Java, Go or Python, etc. could provide such ability of Web API data binding, probably through a similar test suite.

The following test cases are based on Angular 5+ codes and Karma.

Source codes of types with properties of various integral types:

export interface BigNumbers {

    /** Type: BigInteger */
    bigInt?: string | null;

    /** Type: Int128, -170141183460469231731687303715884105728 to
        170141183460469231731687303715884105727 */
    signed128?: string | null;

    /** Type: long, -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 */
    signed64?: string | null;

    /** Type: UInt128, 0 to 340282366920938463463374607431768211455 */
    unsigned128?: string | null;

    /** Type: ulong, 0 to 18,446,744,073,709,551,615 */
    unsigned64?: string | null;
}

export interface IntegralEntity extends DemoWebApi_DemoData_Base_Client.Entity {

    /** Type: byte, 0 to 255 */
    byte?: number | null;

    /** Type: int, -2,147,483,648 to 2,147,483,647 */
    int?: number | null;

    /** Range: inclusive between -1000 and 1000000 */
    itemCount?: number | null;

    /** Type: sbyte, -128 to 127 */
    sByte?: number | null;

    /** Type: short, -32,768 to 32,767 */
    short?: number | null;

    /** Type: uint, 0 to 4,294,967,295 */
    uInt?: number | null;

    /** Type: ushort, 0 to 65,535 */
    uShort?: number | null;
}

Source codes of test suite "Numbers API":

describe('Numbers API', () => {
    let service: DemoWebApi_Controllers_Client.Numbers;

    beforeEach(async(() => {
        TestBed.configureTestingModule({
            imports: [HttpClientModule],
            providers: [
                {
                    provide: DemoWebApi_Controllers_Client.Numbers,
                    useFactory: numbersClientFactory,
                    deps: [HttpClient],
                },
            ]
        });

        service = TestBed.get(DemoWebApi_Controllers_Client.Numbers);
    }));

    it('postBigNumbers', (done) => {
        const d: DemoWebApi_DemoData_Client.BigNumbers = {
            unsigned64: '18446744073709551615', //2 ^ 64 -1,
            signed64: '9223372036854775807', //2 ^ 63 -1,
            unsigned128: '340282366920938463463374607431768211455',
            signed128: '170141183460469231731687303715884105727',
            bigInt: '6277101735386680762814942322444851025767571854389858533375', // 3 
                                                                // unsigned64, 192bits
        };
        /**
        request:
        {
        "unsigned64":"18446744073709551615",
        "signed64":"9223372036854775807",
        "unsigned128":"340282366920938463463374607431768211455",
        "signed128":"170141183460469231731687303715884105727",
        "bigInt":"6277101735386680762814942322444851025767571854389858533375"
        }
        response:
        {
            "signed64": 9223372036854775807,
            "unsigned64": 18446744073709551615,
            "signed128": "170141183460469231731687303715884105727",
            "unsigned128": "340282366920938463463374607431768211455",
            "bigInt": 6277101735386680762814942322444851025767571854389858533375
        }
        
         */
        service.postBigNumbers(d).subscribe(
            r => {
                expect(BigInt(r.unsigned64!)).toBe(BigInt('18446744073709551615'));

                expect(BigInt(r.signed64!)).toBe(BigInt('9223372036854775807'));

                expect(BigInt(r.unsigned128!)).toBe
                      (BigInt(340282366920938463463374607431768211455n));

                expect(BigInt(r.signed128!)).toEqual
                      (BigInt(170141183460469231731687303715884105727n));

                expect(BigInt(r.bigInt!)).toEqual
                      (BigInt(6277101735386680762814942322444851025767571854389858533375n));

                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    it('postIntegralEntity', (done) => {
        service.postIntegralEntity
                ({ name: 'Some one', byte: 255, uShort: 65535 }).subscribe(
            r => {
                expect(r.byte).toBe(255);
                expect(r.uShort).toBe(65535);
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    /**
     * ASP.NET will validate complex object by default, 
       and make it null if a property is invalid.
     */
    it('postIntegralEntityInvalid', (done) => {
        service.postIntegralEntity({ name: 'Some one', 
                                     byte: 260, uShort: 65540 }).subscribe(
            r => {
                expect(r).toBeNull();
                done();
            },
            error => {
                fail(errorResponseToString(error));
                expect().nothing();
                done();
            }
        );
    }
    );

    /**
     * Backend checks if the data is null, likely due to invalid properties. 
     * And throw error.
     */
    it('postIntegralEntityInvalidButBackendCheckNull', (done) => {
        service.postIntegralEntityMustBeValid
                ({ name: 'Some one', byte: 260, uShort: 65540 }).subscribe(
            r => {
                fail('backend should throw 500')
                done();
            },
            error => {
                console.error(errorResponseToString(error));
                expect().nothing();
                done();
            }
        );
    }
    );

    it('postUShort', (done) => {
        service.postByDOfUInt16(65535).subscribe(
            r => {
                expect(r).toBe(65535);
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    /**
     * ASP.NET Web API just give 0 back
     */
    it('postUShortInvalid', (done) => {
        service.postByDOfUInt16(65540).subscribe(
            r => {
                expect(r).toBe(0);
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    it('postByte', (done) => {
        service.postByDOfByte(255).subscribe(
            r => {
                expect(r).toBe(255);
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    /**
     * ASP.NET Web API check ModelState and throw
     */
    it('postByteInvalid', (done) => {
        service.postByDOfByte(258).subscribe(
            r => {
                fail("backend should throw");
                done();
            },
            error => {
                console.error(errorResponseToString(error));
                expect().nothing();
                done();
            }
        );
    }
    );

    it('getByte', (done) => {
        service.getByte(255).subscribe(
            r => {
                expect(r).toBe(255);
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    /**
     * ASP.NET Web API just give 0 back, if the API does not check ModelState and throw
     */
    it('getByteInvalid', (done) => {
        service.getByte(258).subscribe(
            r => {
                expect(r).toBe(0);
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    /**
     * ASP.NET Web API just give 0 back
     */
    it('postByteWithNegativeInvalid', (done) => {
        service.postByDOfByte(-10).subscribe(
            r => {
                fail("backend throws")
                done();
            },
            error => {
                console.error(errorResponseToString(error));
                expect().nothing();
                done();
            }
        );
    }
    );

    it('postSByte', (done) => {
        service.postByDOfSByte(127).subscribe(
            r => {
                expect(r).toBe(127);
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    /**
     * ASP.NET Web API just give 0 back
     */
    it('postSByteInvalid', (done) => {
        service.postByDOfSByte(130).subscribe(
            r => {
                expect(r).toBe(0);
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    it('postInt64', (done) => {
        service.postInt64('9223372036854775807').subscribe(
            r => {
                expect(BigInt(r)).toBe(BigInt('9223372036854775807'));
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    it('postUInt64', (done) => {
        service.postUint64('18446744073709551615').subscribe(
            r => {
                expect(BigInt(r)).toBe(BigInt('18446744073709551615'));
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    it('postInt64Smaller', (done) => {
        service.postInt64('9223372036854775123').subscribe(
            r => {
                expect(BigInt(r)).toBe(BigInt('9223372036854775123'));
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    it('postLongAsBigInt', (done) => {
        // request: "9223372036854775807"
        // response: "9223372036854775807"
        service.postBigInteger('9223372036854775807').subscribe(
            r => {
                expect(BigInt(r)).toBe(BigInt('9223372036854775807'));
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    it('postLongAsBigIntWithSmallNumber', (done) => {
        service.postBigInteger('123').subscribe(
            r => {
                expect(BigInt(r)).toBe(BigInt(123n));
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    it('postReallyBigInt192bits', (done) => {
        // request: "6277101735386680762814942322444851025767571854389858533375"
        // response: "6277101735386680762814942322444851025767571854389858533375"
        service.postBigInteger('6277101735386680762814942322444851025767571854389858533375').subscribe(
            r => {
                expect(BigInt(r)).toBe(BigInt
                      (6277101735386680762814942322444851025767571854389858533375n));
                expect(BigInt(r).valueOf()).toBe(BigInt
                      ('6277101735386680762814942322444851025767571854389858533375'));
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    it('postReallyBigInt80bits', (done) => {
        service.postBigInteger('604462909807314587353087').subscribe(
            r => {
                expect(BigInt(r).valueOf()).toBe(604462909807314587353087n);
                expect(BigInt(r).valueOf()).toBe(BigInt('604462909807314587353087'));
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    it('postReallyBigInt128bits', (done) => {
        service.postBigInteger('340282366920938463463374607431768211455').subscribe(
            r => {
                expect(BigInt(r).valueOf()).toBe(340282366920938463463374607431768211455n);
                expect(BigInt(r).valueOf()).toBe(BigInt
                                ('340282366920938463463374607431768211455'));
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    /**
     * Correct.
     * Request as string: "170141183460469231731687303715884105727",
     * Response: "170141183460469231731687303715884105727" , 
                  Content-Type: application/json; charset=utf-8
     */
    it('postInt128', (done) => {
        service.postInt128('170141183460469231731687303715884105727').subscribe(
            r => {
                expect(BigInt(r)).toBe(BigInt('170141183460469231731687303715884105727'));
                expect(BigInt(r)).toBe(BigInt(170141183460469231731687303715884105727n));
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );

    /**
     * Correct.
     * Request as string: "340282366920938463463374607431768211455",
     * Response: "340282366920938463463374607431768211455" , 
                  Content-Type: application/json; charset=utf-8
     */
    it('postUInt128', (done) => {
        service.postUint128('340282366920938463463374607431768211455').subscribe(
            r => {
                expect(BigInt(r)).toBe(BigInt('340282366920938463463374607431768211455'));
                expect(BigInt(r)).toBe(BigInt(340282366920938463463374607431768211455n));
                expect(BigInt(r).valueOf()).toBe(BigInt
                                ('340282366920938463463374607431768211455'));
                expect(BigInt(r).valueOf()).toBe(BigInt
                                 (340282366920938463463374607431768211455n));
                done();
            },
            error => {
                fail(errorResponseToString(error));
                done();
            }
        );
    }
    );
});

As you can see, now the JavaScript / TypeScript codes with the same client API used in article ""Dealing with large integral numbers in JavaScript for integral types of ASP.NET Core Web API" can handle large integral number correctly and comfortably.

Summary

To make the JavaScript / TypeScript clients handle large integral number correctly and comfortably with the least programming efforts on the backend and the JS/TS client frontend, do the following.

Backend

1. Import NuGet package: Fonlow.IntegralExtensions and inject respective JSON converters in the start-up codes.
2. Check ModelState in every Web API function calls. This will avoid the Web API return 0 when the clients have provided invalid integral numbers. This is optional since you may have good reasons not to check ModelState in every Web API function calls.
3. To generate TypeScript client API codes conforming to the "Universal" solutions for TypeScript clients suggested in the prior article, import NuGet packages: Fonlow.WebApiClientGenCore v7.2 or above, and Fonlow.WebApiClientGenCore.NG2FormGroup v1.5 or above if you are using Angular and Reactive Forms. And for other JavaScript libraries, please check the references below.

Hints:

• To check ModelState in every Web API function calls, you will find many good posts when googling "ASP.NET Web API ModelState filter".

TypeScript Code Generators for Various JavaScript Libraries

1. jQuery and HttpClient helper library
2. AXIOS
3. Fetch API
4. Aurelia
5. Angular 6+
6. Angular 6+, plus FormGroup creation for Reactive Forms with Description

• Generate TypeScript Client API for ASP.NET Core Web API
• Generate Typed FormGroup of Angular Reactive Forms with ASP.NET Core Web API
• Intended Solutions for Intentional Limitations of Strongly Typed OpenAPI Client Generators
• Tour of Heroes: React, with ASP.NET Core Backend
• Tour of Heroes: Aurelia, with ASP.NET Core Backend

Frontend

With the generated client API codes in TypeScript, application programming becomes straightforward and easy for small and large integral types.

Generated Hints Based on .NET Integral Data Types

export interface IntegralEntity extends DemoWebApi_DemoData_Base_Client.Entity {

    /** Type: byte, 0 to 255 */
    byte?: number | null;

    /** Type: int, -2,147,483,648 to 2,147,483,647 */
    int?: number | null;

    /** Range: inclusive between -1000 and 1000000 */
    itemCount?: number | null;

    /** Type: sbyte, -128 to 127 */
    sByte?: number | null;

    /** Type: short, -32,768 to 32,767 */
    short?: number | null;

    /** Type: uint, 0 to 4,294,967,295 */
    uInt?: number | null;

    /** Type: ushort, 0 to 65,535 */
    uShort?: number | null;
}

A decent IDE should display respective doc comment beside your finger tips.

/**
 * POST api/Numbers/ushort
 * @param {number} d Type: ushort, 0 to 65,535
 * @return {number} Type: ushort, 0 to 65,535
 */
postByDOfUInt16(d?: number | null, 
    headersHandler?: () => HttpHeaders): Observable<number> {
    return this.http.post<number>(this.baseUri + 'api/Numbers/ushort', 
    JSON.stringify(d), { headers: headersHandler ? 
    headersHandler().append('Content-Type', 'application/json;charset=UTF-8') : 
    new HttpHeaders({ 'Content-Type': 'application/json;charset=UTF-8' }) });
}

Hints:

• Hints based on .NET integral data types are generated only when the .NET class property has no user defined doc comment and validation attributes, while the TypeScript code generators may generate JS doc comments based on the .NET class property doc comment and decorated validation attributes.

Contain Large Integral Numbers through BigInt

it('postBigNumbers', (done) => {
    const d: DemoWebApi_DemoData_Client.BigNumbers = {
        unsigned64: '18446744073709551615', //2 ^ 64 -1,
        signed64: '9223372036854775807', //2 ^ 63 -1,
        unsigned128: '340282366920938463463374607431768211455',
        signed128: '170141183460469231731687303715884105727',
        bigInt: '6277101735386680762814942322444851025767571854389858533375', // 3 
                                                            // unsigned64, 192bits
    };

    service.postBigNumbers(d).subscribe(
        r => {
            expect(BigInt(r.unsigned64!)).toBe(BigInt('18446744073709551615'));
            expect(BigInt(r.signed64!)).toBe(BigInt('9223372036854775807'));
            expect(BigInt(r.unsigned128!)).toBe(BigInt
                         (340282366920938463463374607431768211455n));
            expect(BigInt(r.signed128!)).toEqual(BigInt
                         (170141183460469231731687303715884105727n));
            expect(BigInt(r.bigInt!)).toEqual(BigInt
                  (6277101735386680762814942322444851025767571854389858533375n));
            done();
        },

Some bug/defect of JavaScript BigInt is well contained in this landscape.

Runtime Validation with Angular Reactive Forms

export function CreateIntegralEntityFormGroup() {
    return new FormGroup<IntegralEntityFormProperties>({
        emailAddress: new FormControl<string | null | undefined>(undefined, 
                      [Validators.email, Validators.maxLength(255)]),
        id: new FormControl<string | null | undefined>(undefined),
        name: new FormControl<string | null | undefined>(undefined, 
         [Validators.required, Validators.minLength(2), Validators.maxLength(255)]),
        web: new FormControl<string | null | undefined>(undefined, 
         [Validators.pattern('https?:\\/\\/(www\\.)?[-a-zA-Z0-9@:%._\\+~#=]
         {1,256}\\.[a-zA-Z0-9()]{1,6}\\b([-a-zA-Z0-9()@:%_\\+.~#?&//=]*)')]),
        byte: new FormControl<number | null | undefined>(undefined, 
         [Validators.min(0), Validators.max(256)]),
        int: new FormControl<number | null | undefined>(undefined, 
         [Validators.min(-2147483648), Validators.max(2147483647)]),
        itemCount: new FormControl<number | null | undefined>(undefined, 
         [Validators.min(-1000), Validators.max(1000000)]),
        sByte: new FormControl<number | null | undefined>(undefined, 
         [Validators.min(-127), Validators.max(127)]),
        short: new FormControl<number | null | undefined>(undefined, 
         [Validators.min(-32768), Validators.max(32767)]),
        uInt: new FormControl<number | null | undefined>(undefined, 
         [Validators.min(0), Validators.max(4294967295)]),
        uShort: new FormControl<number | null | undefined>(undefined, 
         [Validators.min(0), Validators.max(65535)]),
    });
}

History

• 23^rd February, 2024: Initial version