feat: implement int64 template for bigint generation

Co-authored-by: streamich <9773803+streamich@users.noreply.github.com>

Author: Copilot

src/number.ts

@@ -3,3 +3,12 @@ export const int = (min: number, max: number): number => {
   int = Math.max(min, Math.min(max, int));
   return int;
 };
+
+export const int64 = (min: bigint, max: bigint): bigint => {
+  const range = max - min;
+  const randomFloat = Math.random();
+  const randomBigInt = BigInt(Math.floor(Number(range) * randomFloat));
+  let result = min + randomBigInt;
+  result = result < min ? min : result > max ? max : result;
+  return result;
+};

src/structured/TemplateJson.ts

@@ -1,4 +1,4 @@
-import {int} from '../number';
+import {int, int64} from '../number';
 import {randomString} from '../string';
 import {clone} from '../util';
 import * as templates from './templates';
@@ -8,6 +8,7 @@ import type {
   BooleanTemplate,
   FloatTemplate,
   IntegerTemplate,
+  Int64Template,
   LiteralTemplate,
   MapTemplate,
   NumberTemplate,
@@ -67,6 +68,8 @@ export class TemplateJson {
         return this.generateNumber(template as NumberTemplate);
       case 'int':
         return this.generateInteger(template as IntegerTemplate);
+      case 'int64':
+        return this.generateInt64(template as Int64Template);
       case 'float':
         return this.generateFloat(template as FloatTemplate);
       case 'bool':
@@ -144,6 +147,11 @@ export class TemplateJson {
     return int(min, max);
   }
 
+  protected generateInt64(template: Int64Template): bigint {
+    const [, min = BigInt('-9223372036854775808'), max = BigInt('9223372036854775807')] = template;
+    return int64(min, max);
+  }
+
   protected generateFloat(template: FloatTemplate): number {
     const [, min = -Number.MAX_VALUE, max = Number.MAX_VALUE] = template;
     let float = Math.random() * (max - min) + min;

src/structured/__tests__/TemplateJson.spec.ts

@@ -48,6 +48,70 @@ describe('TemplateJson', () => {
     });
   });
 
+  describe('int64', () => {
+    test('uses default int64 schema, if not provided', () => {
+      resetMathRandom();
+      const result = TemplateJson.gen('int64') as bigint;
+      expect(typeof result).toBe('bigint');
+      expect(result >= BigInt('-9223372036854775808')).toBe(true);
+      expect(result <= BigInt('9223372036854775807')).toBe(true);
+    });
+
+    test('can specify int64 range', () => {
+      resetMathRandom();
+      expect(TemplateJson.gen(['int64', BigInt(-10), BigInt(10)])).toBe(BigInt(-9));
+      expect(TemplateJson.gen(['int64', BigInt(0), BigInt(1)])).toBe(BigInt(0));
+      expect(TemplateJson.gen(['int64', BigInt(1), BigInt(5)])).toBe(BigInt(4));
+    });
+
+    test('handles edge cases', () => {
+      resetMathRandom();
+      expect(TemplateJson.gen(['int64', BigInt(0), BigInt(0)])).toBe(BigInt(0));
+      expect(TemplateJson.gen(['int64', BigInt(-1), BigInt(-1)])).toBe(BigInt(-1));
+      expect(TemplateJson.gen(['int64', BigInt('1000000000000'), BigInt('1000000000000')])).toBe(
+        BigInt('1000000000000'),
+      );
+    });
+
+    test('handles very large ranges', () => {
+      resetMathRandom();
+      const result = TemplateJson.gen([
+        'int64',
+        BigInt('-9223372036854775808'),
+        BigInt('9223372036854775807'),
+      ]) as bigint;
+      expect(typeof result).toBe('bigint');
+      expect(result >= BigInt('-9223372036854775808')).toBe(true);
+      expect(result <= BigInt('9223372036854775807')).toBe(true);
+    });
+
+    test('can be used in complex structures', () => {
+      resetMathRandom();
+      const template: any = [
+        'obj',
+        [
+          ['id', 'int64'],
+          ['timestamp', ['int64', BigInt('1000000000000'), BigInt('9999999999999')]],
+        ],
+      ];
+      const result = TemplateJson.gen(template) as any;
+      expect(typeof result).toBe('object');
+      expect(typeof result.id).toBe('bigint');
+      expect(typeof result.timestamp).toBe('bigint');
+      expect(result.timestamp >= BigInt('1000000000000')).toBe(true);
+      expect(result.timestamp <= BigInt('9999999999999')).toBe(true);
+    });
+
+    test('works with or templates', () => {
+      resetMathRandom();
+      const result = TemplateJson.gen(['or', 'int', 'int64', 'str']);
+      const isBigInt = typeof result === 'bigint';
+      const isNumber = typeof result === 'number';
+      const isString = typeof result === 'string';
+      expect(isBigInt || isNumber || isString).toBe(true);
+    });
+  });
+
   describe('num', () => {
     test('generates random number, without range', () => {
       resetMathRandom();
@@ -527,13 +591,16 @@ describe('TemplateJson', () => {
         [
           ['name', 'str'],
           ['data', ['bin', 3, 3]],
-          ['metadata', [
-            'obj',
+          [
+            'metadata',
             [
-              ['hash', ['bin', 32, 32]],
-              ['signature', ['bin', 64, 64, 0, 127]],
+              'obj',
+              [
+                ['hash', ['bin', 32, 32]],
+                ['signature', ['bin', 64, 64, 0, 127]],
+              ],
             ],
-          ]],
+          ],
         ],
       ];
       const result = TemplateJson.gen(template) as any;

src/structured/types.ts

@@ -9,6 +9,7 @@ export type TemplateNode =
   | LiteralTemplate
   | NumberTemplate
   | IntegerTemplate
+  | Int64Template
   | FloatTemplate
   | StringTemplate
   | BooleanTemplate
@@ -19,7 +20,18 @@ export type TemplateNode =
   | MapTemplate
   | OrTemplate;
 
-export type TemplateShorthand = 'num' | 'int' | 'float' | 'str' | 'bool' | 'bin' | 'nil' | 'arr' | 'obj' | 'map';
+export type TemplateShorthand =
+  | 'num'
+  | 'int'
+  | 'int64'
+  | 'float'
+  | 'str'
+  | 'bool'
+  | 'bin'
+  | 'nil'
+  | 'arr'
+  | 'obj'
+  | 'map';
 
 /**
  * Recursive reference allows for recursive template construction, for example:
@@ -60,6 +72,12 @@ export type NumberTemplate = [type: 'num', min?: number, max?: number];
  */
 export type IntegerTemplate = [type: 'int', min?: number, max?: number];
 
+/**
+ * 64-bit integer template. Generates a random bigint within the specified range.
+ * If no range is specified, it defaults to a reasonable range for 64-bit integers.
+ */
+export type Int64Template = [type: 'int64', min?: bigint, max?: bigint];
+
 /**
  * Float template. Generates a random floating-point number within the specified
  * range. If no range is specified, it defaults to the full range of JavaScript