docs: add a section for numbers

.changeset/loud-wolves-rest.md

@@ -0,0 +1,2 @@
+---
+---

apps/docs-snippets/src/guide/types/numbers.test.ts

@@ -0,0 +1,45 @@
+import { bn } from 'fuels';
+
+import { DocSnippetProjectsEnum } from '../../../test/fixtures/forc-projects';
+import { createAndDeployContractFromProject } from '../../utils';
+
+/**
+ * @group node
+ */
+describe(__filename, () => {
+  test('should successfully create new Sway-compatible BigNumber from a JavaScript number', () => {
+    // #region numbers-docs-1
+    // #context import { bn } from 'fuels';
+
+    const originalNumber = 20;
+
+    const bigNumber = bn(originalNumber);
+
+    expect(bigNumber.toNumber()).toEqual(originalNumber);
+    // #endregion numbers-docs-1
+  });
+
+  test('should successfully create new Sway-compatible BigNumber from a string', () => {
+    // #region numbers-docs-2
+    // #context import { bn } from 'fuels';
+
+    const originalNumber = '9007199254740992';
+
+    const bigNumber = bn(originalNumber);
+
+    expect(bigNumber.toString()).toEqual(originalNumber);
+    // #endregion numbers-docs-2
+  });
+
+  test('should succcesfully pass in and read a number to/from a contract', async () => {
+    const contract = await createAndDeployContractFromProject(DocSnippetProjectsEnum.ECHO_VALUES);
+
+    // #region numbers-docs-3
+    const originalNumber = 20;
+
+    const { value } = await contract.functions.echo_u64(bn(originalNumber)).call();
+
+    expect(value.toNumber()).toEqual(originalNumber);
+    // #endregion numbers-docs-3
+  });
+});

apps/docs-snippets/test/fixtures/forc-projects/echo-values/src/main.sw

@@ -13,6 +13,8 @@ abi EchoValues {
     fn echo_tuple(tuple: (u8, bool, u64)) -> (u8, bool, u64);
 
     fn echo_b512(input: B512) -> B512;
+
+    fn echo_u64(value: u64) -> u64;
 }
 
 impl EchoValues for Contract {
@@ -44,5 +46,8 @@ impl EchoValues for Contract {
         input
     }
     // #endregion bits512-3
+    fn echo_u64(value: u64) -> u64 {
+        value
+    }
 }
 // #endregion understanding-fuel-binary-file

apps/docs/.vitepress/config.ts

@@ -124,6 +124,10 @@ export default defineConfig({
                 text: 'Bytes32',
                 link: '/guide/types/bytes32',
               },
+              {
+                text: 'Numbers',
+                link: '/guide/types/numbers',
+              },
               {
                 text: 'String',
                 link: '/guide/types/string',

apps/docs/src/guide/types/numbers.md

@@ -0,0 +1,29 @@
+# Numbers
+
+In Sway, there are multiple types of numbers:
+
+1. `u8` (8-bit unsigned integer)
+2. `u16` (16-bit unsigned integer)
+3. `u32` (32-bit unsigned integer)
+4. `u64` (64-bit unsigned integer)
+5. `u256` (256-bit unsigned integer)
+
+Conveniently, all of these types are handled the same way in the TS SDK. This guide explains how to create and interact with Sway numbers while using the SDK.
+
+## Creating Numbers
+
+Just like Ethereum, when you pass in a number to a Sway program from JavaScript, you must first convert it to a `BigNum` object. Here's how you can do that:
+
+<<< @/../../docs-snippets/src/guide/types/numbers.test.ts#numbers-docs-1{ts:line-numbers}
+
+You can also create a number from a string. This is useful when you want to pass in a number that is too large to be represented as a JavaScript number. Here's how you can do that:
+
+<<< @/../../docs-snippets/src/guide/types/numbers.test.ts#numbers-docs-2{ts:line-numbers}
+
+## Interacting with Numbers in Contract Methods
+
+All numerical inputs and outputs to/from Sway program methods are `BigNumber` objects.
+
+<<< @/../../docs-snippets/src/guide/types/numbers.test.ts#numbers-docs-3{ts:line-numbers}
+
+> Note: If a contract call returns a number that is too large to be represented as a JavaScript number, you can convert it to a string using the `.toString()` method instead of `.toNumber()`.