@solana/codecs-numbers 6.3.1 → 6.3.2-canary-20260313112147

package/src/i32.ts

@@ -0,0 +1,105 @@
+import { combineCodec, FixedSizeCodec, FixedSizeDecoder, FixedSizeEncoder } from '@solana/codecs-core';
+
+import { NumberCodecConfig } from './common';
+import { numberDecoderFactory, numberEncoderFactory } from './utils';
+
+/**
+ * Returns an encoder for 32-bit signed integers (`i32`).
+ *
+ * This encoder serializes `i32` values using 4 bytes.
+ * Values can be provided as either `number` or `bigint`.
+ *
+ * For more details, see {@link getI32Codec}.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeEncoder<number | bigint, 4>` for encoding `i32` values.
+ *
+ * @example
+ * Encoding an `i32` value.
+ * ```ts
+ * const encoder = getI32Encoder();
+ * const bytes = encoder.encode(-42); // 0xd6ffffff
+ * ```
+ *
+ * @see {@link getI32Codec}
+ */
+export const getI32Encoder = (config: NumberCodecConfig = {}): FixedSizeEncoder<bigint | number, 4> =>
+    numberEncoderFactory({
+        config,
+        name: 'i32',
+        range: [-Number('0x7fffffff') - 1, Number('0x7fffffff')],
+        set: (view, value, le) => view.setInt32(0, Number(value), le),
+        size: 4,
+    });
+
+/**
+ * Returns a decoder for 32-bit signed integers (`i32`).
+ *
+ * This decoder deserializes `i32` values from 4 bytes.
+ * The decoded value is always a `number`.
+ *
+ * For more details, see {@link getI32Codec}.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeDecoder<number, 4>` for decoding `i32` values.
+ *
+ * @example
+ * Decoding an `i32` value.
+ * ```ts
+ * const decoder = getI32Decoder();
+ * const value = decoder.decode(new Uint8Array([0xd6, 0xff, 0xff, 0xff])); // -42
+ * ```
+ *
+ * @see {@link getI32Codec}
+ */
+export const getI32Decoder = (config: NumberCodecConfig = {}): FixedSizeDecoder<number, 4> =>
+    numberDecoderFactory({
+        config,
+        get: (view, le) => view.getInt32(0, le),
+        name: 'i32',
+        size: 4,
+    });
+
+/**
+ * Returns a codec for encoding and decoding 32-bit signed integers (`i32`).
+ *
+ * This codec serializes `i32` values using 4 bytes.
+ * Values can be provided as either `number` or `bigint`, but the decoded value is always a `number`.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeCodec<number | bigint, number, 4>` for encoding and decoding `i32` values.
+ *
+ * @example
+ * Encoding and decoding an `i32` value.
+ * ```ts
+ * const codec = getI32Codec();
+ * const bytes = codec.encode(-42); // 0xd6ffffff
+ * const value = codec.decode(bytes); // -42
+ * ```
+ *
+ * @example
+ * Using big-endian encoding.
+ * ```ts
+ * const codec = getI32Codec({ endian: Endian.Big });
+ * const bytes = codec.encode(-42); // 0xffffffd6
+ * ```
+ *
+ * @remarks
+ * This codec supports values between `-2^31` (`-2,147,483,648`) and `2^31 - 1` (`2,147,483,647`).
+ *
+ * - If you need a smaller signed integer, consider using {@link getI16Codec} or {@link getI8Codec}.
+ * - If you need a larger signed integer, consider using {@link getI64Codec}.
+ * - If you need unsigned integers, consider using {@link getU32Codec}.
+ *
+ * Separate {@link getI32Encoder} and {@link getI32Decoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getI32Encoder().encode(-42);
+ * const value = getI32Decoder().decode(bytes);
+ * ```
+ *
+ * @see {@link getI32Encoder}
+ * @see {@link getI32Decoder}
+ */
+export const getI32Codec = (config: NumberCodecConfig = {}): FixedSizeCodec<bigint | number, number, 4> =>
+    combineCodec(getI32Encoder(config), getI32Decoder(config));

package/src/i64.ts

@@ -0,0 +1,108 @@
+import { combineCodec, FixedSizeCodec, FixedSizeDecoder, FixedSizeEncoder } from '@solana/codecs-core';
+
+import { NumberCodecConfig } from './common';
+import { numberDecoderFactory, numberEncoderFactory } from './utils';
+
+/**
+ * Returns an encoder for 64-bit signed integers (`i64`).
+ *
+ * This encoder serializes `i64` values using 8 bytes.
+ * Values can be provided as either `number` or `bigint`.
+ *
+ * For more details, see {@link getI64Codec}.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeEncoder<number | bigint, 8>` for encoding `i64` values.
+ *
+ * @example
+ * Encoding an `i64` value.
+ * ```ts
+ * const encoder = getI64Encoder();
+ * const bytes = encoder.encode(-42n); // 0xd6ffffffffffffff
+ * ```
+ *
+ * @see {@link getI64Codec}
+ */
+export const getI64Encoder = (config: NumberCodecConfig = {}): FixedSizeEncoder<bigint | number, 8> =>
+    numberEncoderFactory({
+        config,
+        name: 'i64',
+        range: [-BigInt('0x7fffffffffffffff') - 1n, BigInt('0x7fffffffffffffff')],
+        set: (view, value, le) => view.setBigInt64(0, BigInt(value), le),
+        size: 8,
+    });
+
+/**
+ * Returns a decoder for 64-bit signed integers (`i64`).
+ *
+ * This decoder deserializes `i64` values from 8 bytes.
+ * The decoded value is always a `bigint`.
+ *
+ * For more details, see {@link getI64Codec}.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeDecoder<bigint, 8>` for decoding `i64` values.
+ *
+ * @example
+ * Decoding an `i64` value.
+ * ```ts
+ * const decoder = getI64Decoder();
+ * const value = decoder.decode(new Uint8Array([
+ *   0xd6, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff
+ * ])); // -42n
+ * ```
+ *
+ * @see {@link getI64Codec}
+ */
+export const getI64Decoder = (config: NumberCodecConfig = {}): FixedSizeDecoder<bigint, 8> =>
+    numberDecoderFactory({
+        config,
+        get: (view, le) => view.getBigInt64(0, le),
+        name: 'i64',
+        size: 8,
+    });
+
+/**
+ * Returns a codec for encoding and decoding 64-bit signed integers (`i64`).
+ *
+ * This codec serializes `i64` values using 8 bytes.
+ * Values can be provided as either `number` or `bigint`, but the decoded value is always a `bigint`.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeCodec<number | bigint, bigint, 8>` for encoding and decoding `i64` values.
+ *
+ * @example
+ * Encoding and decoding an `i64` value.
+ * ```ts
+ * const codec = getI64Codec();
+ * const bytes = codec.encode(-42n); // 0xd6ffffffffffffff
+ * const value = codec.decode(bytes); // -42n
+ * ```
+ *
+ * @example
+ * Using big-endian encoding.
+ * ```ts
+ * const codec = getI64Codec({ endian: Endian.Big });
+ * const bytes = codec.encode(-42n); // 0xffffffffffffffd6
+ * ```
+ *
+ * @remarks
+ * This codec supports values between `-2^63` and `2^63 - 1`.
+ * Since JavaScript `number` cannot safely represent values beyond `2^53 - 1`, the decoded value is always a `bigint`.
+ *
+ * - If you need a smaller signed integer, consider using {@link getI32Codec} or {@link getI16Codec}.
+ * - If you need a larger signed integer, consider using {@link getI128Codec}.
+ * - If you need unsigned integers, consider using {@link getU64Codec}.
+ *
+ * Separate {@link getI64Encoder} and {@link getI64Decoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getI64Encoder().encode(-42);
+ * const value = getI64Decoder().decode(bytes);
+ * ```
+ *
+ * @see {@link getI64Encoder}
+ * @see {@link getI64Decoder}
+ */
+export const getI64Codec = (config: NumberCodecConfig = {}): FixedSizeCodec<bigint | number, bigint, 8> =>
+    combineCodec(getI64Encoder(config), getI64Decoder(config));

package/src/i8.ts

@@ -0,0 +1,91 @@
+import { combineCodec, FixedSizeCodec, FixedSizeDecoder, FixedSizeEncoder } from '@solana/codecs-core';
+
+import { numberDecoderFactory, numberEncoderFactory } from './utils';
+
+/**
+ * Returns an encoder for 8-bit signed integers (`i8`).
+ *
+ * This encoder serializes `i8` values using 1 byte.
+ * Values can be provided as either `number` or `bigint`.
+ *
+ * For more details, see {@link getI8Codec}.
+ *
+ * @returns A `FixedSizeEncoder<number | bigint, 1>` for encoding `i8` values.
+ *
+ * @example
+ * Encoding an `i8` value.
+ * ```ts
+ * const encoder = getI8Encoder();
+ * const bytes = encoder.encode(-42); // 0xd6
+ * ```
+ *
+ * @see {@link getI8Codec}
+ */
+export const getI8Encoder = (): FixedSizeEncoder<bigint | number, 1> =>
+    numberEncoderFactory({
+        name: 'i8',
+        range: [-Number('0x7f') - 1, Number('0x7f')],
+        set: (view, value) => view.setInt8(0, Number(value)),
+        size: 1,
+    });
+
+/**
+ * Returns a decoder for 8-bit signed integers (`i8`).
+ *
+ * This decoder deserializes `i8` values from 1 byte.
+ * The decoded value is always a `number`.
+ *
+ * For more details, see {@link getI8Codec}.
+ *
+ * @returns A `FixedSizeDecoder<number, 1>` for decoding `i8` values.
+ *
+ * @example
+ * Decoding an `i8` value.
+ * ```ts
+ * const decoder = getI8Decoder();
+ * const value = decoder.decode(new Uint8Array([0xd6])); // -42
+ * ```
+ *
+ * @see {@link getI8Codec}
+ */
+export const getI8Decoder = (): FixedSizeDecoder<number, 1> =>
+    numberDecoderFactory({
+        get: view => view.getInt8(0),
+        name: 'i8',
+        size: 1,
+    });
+
+/**
+ * Returns a codec for encoding and decoding 8-bit signed integers (`i8`).
+ *
+ * This codec serializes `i8` values using 1 byte.
+ * Values can be provided as either `number` or `bigint`, but the decoded value is always a `number`.
+ *
+ * @returns A `FixedSizeCodec<number | bigint, number, 1>` for encoding and decoding `i8` values.
+ *
+ * @example
+ * Encoding and decoding an `i8` value.
+ * ```ts
+ * const codec = getI8Codec();
+ * const bytes = codec.encode(-42); // 0xd6
+ * const value = codec.decode(bytes); // -42
+ * ```
+ *
+ * @remarks
+ * This codec supports values between `-2^7` (`-128`) and `2^7 - 1` (`127`).
+ *
+ * - If you need a larger signed integer, consider using {@link getI16Codec}.
+ * - If you need an unsigned integer, consider using {@link getU8Codec}.
+ *
+ * Separate {@link getI8Encoder} and {@link getI8Decoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getI8Encoder().encode(-42);
+ * const value = getI8Decoder().decode(bytes);
+ * ```
+ *
+ * @see {@link getI8Encoder}
+ * @see {@link getI8Decoder}
+ */
+export const getI8Codec = (): FixedSizeCodec<bigint | number, number, 1> =>
+    combineCodec(getI8Encoder(), getI8Decoder());

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * This package contains codecs for numbers of different sizes and endianness.
+ * It can be used standalone, but it is also exported as part of Kit
+ * [`@solana/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit).
+ *
+ * This package is also part of the [`@solana/codecs` package](https://github.com/anza-xyz/kit/tree/main/packages/codecs)
+ * which acts as an entry point for all codec packages as well as for their documentation.
+ *
+ * @packageDocumentation
+ */
+export * from './assertions';
+export * from './common';
+export * from './f32';
+export * from './f64';
+export * from './i128';
+export * from './i16';
+export * from './i32';
+export * from './i64';
+export * from './i8';
+export * from './short-u16';
+export * from './u128';
+export * from './u16';
+export * from './u32';
+export * from './u64';
+export * from './u8';

package/src/short-u16.ts

@@ -0,0 +1,158 @@
+import {
+    combineCodec,
+    createDecoder,
+    createEncoder,
+    Offset,
+    ReadonlyUint8Array,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+
+import { assertNumberIsBetweenForCodec } from './assertions';
+
+/**
+ * Returns an encoder for `shortU16` values.
+ *
+ * This encoder serializes `shortU16` values using **1 to 3 bytes**.
+ * Smaller values use fewer bytes, while larger values take up more space.
+ *
+ * For more details, see {@link getShortU16Codec}.
+ *
+ * @returns A `VariableSizeEncoder<number | bigint>` for encoding `shortU16` values.
+ *
+ * @example
+ * Encoding a `shortU16` value.
+ * ```ts
+ * const encoder = getShortU16Encoder();
+ * encoder.encode(42);    // 0x2a
+ * encoder.encode(128);   // 0x8001
+ * encoder.encode(16384); // 0x808001
+ * ```
+ *
+ * @see {@link getShortU16Codec}
+ */
+export const getShortU16Encoder = (): VariableSizeEncoder<bigint | number> =>
+    createEncoder({
+        getSizeFromValue: (value: bigint | number): number => {
+            if (value <= 0b01111111) return 1;
+            if (value <= 0b0011111111111111) return 2;
+            return 3;
+        },
+        maxSize: 3,
+        write: (value: bigint | number, bytes: Uint8Array, offset: Offset): Offset => {
+            assertNumberIsBetweenForCodec('shortU16', 0, 65535, value);
+            const shortU16Bytes = [0];
+            for (let ii = 0; ; ii += 1) {
+                // Shift the bits of the value over such that the next 7 bits are at the right edge.
+                const alignedValue = Number(value) >> (ii * 7);
+                if (alignedValue === 0) {
+                    // No more bits to consume.
+                    break;
+                }
+                // Extract those 7 bits using a mask.
+                const nextSevenBits = 0b1111111 & alignedValue;
+                shortU16Bytes[ii] = nextSevenBits;
+                if (ii > 0) {
+                    // Set the continuation bit of the previous slice.
+                    shortU16Bytes[ii - 1] |= 0b10000000;
+                }
+            }
+            bytes.set(shortU16Bytes, offset);
+            return offset + shortU16Bytes.length;
+        },
+    });
+
+/**
+ * Returns a decoder for `shortU16` values.
+ *
+ * This decoder deserializes `shortU16` values from **1 to 3 bytes**.
+ * The number of bytes used depends on the encoded value.
+ *
+ * For more details, see {@link getShortU16Codec}.
+ *
+ * @returns A `VariableSizeDecoder<number>` for decoding `shortU16` values.
+ *
+ * @example
+ * Decoding a `shortU16` value.
+ * ```ts
+ * const decoder = getShortU16Decoder();
+ * decoder.decode(new Uint8Array([0x2a]));             // 42
+ * decoder.decode(new Uint8Array([0x80, 0x01]));       // 128
+ * decoder.decode(new Uint8Array([0x80, 0x80, 0x01])); // 16384
+ * ```
+ *
+ * @see {@link getShortU16Codec}
+ */
+export const getShortU16Decoder = (): VariableSizeDecoder<number> =>
+    createDecoder({
+        maxSize: 3,
+        read: (bytes: ReadonlyUint8Array | Uint8Array, offset): [number, Offset] => {
+            let value = 0;
+            let byteCount = 0;
+            while (++byteCount) {
+                const byteIndex = byteCount - 1;
+                const currentByte = bytes[offset + byteIndex];
+                const nextSevenBits = 0b1111111 & currentByte;
+                // Insert the next group of seven bits into the correct slot of the output value.
+                value |= nextSevenBits << (byteIndex * 7);
+                if ((currentByte & 0b10000000) === 0) {
+                    // This byte does not have its continuation bit set. We're done.
+                    break;
+                }
+            }
+            return [value, offset + byteCount];
+        },
+    });
+
+/**
+ * Returns a codec for encoding and decoding `shortU16` values.
+ *
+ * It serializes unsigned integers using **1 to 3 bytes** based on the encoded value.
+ * The larger the value, the more bytes it uses.
+ *
+ * - If the value is `<= 0x7f` (127), it is stored in a **single byte**
+ *   and the first bit is set to `0` to indicate the end of the value.
+ * - Otherwise, the first bit is set to `1` to indicate that the value continues in the next byte, which follows the same pattern.
+ * - This process repeats until the value is fully encoded in up to 3 bytes. The third and last byte, if needed, uses all 8 bits to store the remaining value.
+ *
+ * In other words, the encoding scheme follows this structure:
+ *
+ * ```txt
+ * 0XXXXXXX                   <- Values 0 to 127 (1 byte)
+ * 1XXXXXXX 0XXXXXXX          <- Values 128 to 16,383 (2 bytes)
+ * 1XXXXXXX 1XXXXXXX XXXXXXXX <- Values 16,384 to 4,194,303 (3 bytes)
+ * ```
+ *
+ * @returns A `VariableSizeCodec<number | bigint, number>` for encoding and decoding `shortU16` values.
+ *
+ * @example
+ * Encoding and decoding `shortU16` values.
+ * ```ts
+ * const codec = getShortU16Codec();
+ * const bytes1 = codec.encode(42);    // 0x2a
+ * const bytes2 = codec.encode(128);   // 0x8001
+ * const bytes3 = codec.encode(16384); // 0x808001
+ *
+ * codec.decode(bytes1); // 42
+ * codec.decode(bytes2); // 128
+ * codec.decode(bytes3); // 16384
+ * ```
+ *
+ * @remarks
+ * This codec efficiently stores small numbers, making it useful for transactions and compact representations.
+ *
+ * If you need a fixed-size `u16` codec, consider using {@link getU16Codec}.
+ *
+ * Separate {@link getShortU16Encoder} and {@link getShortU16Decoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getShortU16Encoder().encode(42);
+ * const value = getShortU16Decoder().decode(bytes);
+ * ```
+ *
+ * @see {@link getShortU16Encoder}
+ * @see {@link getShortU16Decoder}
+ */
+export const getShortU16Codec = (): VariableSizeCodec<bigint | number, number> =>
+    combineCodec(getShortU16Encoder(), getShortU16Decoder());

package/src/u128.ts

@@ -0,0 +1,117 @@
+import { combineCodec, FixedSizeCodec, FixedSizeDecoder, FixedSizeEncoder } from '@solana/codecs-core';
+
+import { NumberCodecConfig } from './common';
+import { numberDecoderFactory, numberEncoderFactory } from './utils';
+
+/**
+ * Returns an encoder for 128-bit unsigned integers (`u128`).
+ *
+ * This encoder serializes `u128` values using sixteen bytes in little-endian format by default.
+ * You may specify big-endian storage using the `endian` option.
+ *
+ * For more details, see {@link getU128Codec}.
+ *
+ * @param config - Optional settings for endianness.
+ * @returns A `FixedSizeEncoder<number | bigint, 16>` for encoding `u128` values.
+ *
+ * @example
+ * Encoding a `u128` value.
+ * ```ts
+ * const encoder = getU128Encoder();
+ * const bytes = encoder.encode(42n); // 0x2a000000000000000000000000000000
+ * ```
+ *
+ * @see {@link getU128Codec}
+ */
+export const getU128Encoder = (config: NumberCodecConfig = {}): FixedSizeEncoder<bigint | number, 16> =>
+    numberEncoderFactory({
+        config,
+        name: 'u128',
+        range: [0n, BigInt('0xffffffffffffffffffffffffffffffff')],
+        set: (view, value, le) => {
+            const leftOffset = le ? 8 : 0;
+            const rightOffset = le ? 0 : 8;
+            const rightMask = 0xffffffffffffffffn;
+            view.setBigUint64(leftOffset, BigInt(value) >> 64n, le);
+            view.setBigUint64(rightOffset, BigInt(value) & rightMask, le);
+        },
+        size: 16,
+    });
+
+/**
+ * Returns a decoder for 128-bit unsigned integers (`u128`).
+ *
+ * This decoder deserializes `u128` values from sixteen bytes in little-endian format by default.
+ * You may specify big-endian storage using the `endian` option.
+ *
+ * For more details, see {@link getU128Codec}.
+ *
+ * @param config - Optional settings for endianness.
+ * @returns A `FixedSizeDecoder<bigint, 16>` for decoding `u128` values.
+ *
+ * @example
+ * Decoding a `u128` value.
+ * ```ts
+ * const decoder = getU128Decoder();
+ * const value = decoder.decode(new Uint8Array([0x2a, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])); // 42n
+ * ```
+ *
+ * @see {@link getU128Codec}
+ */
+export const getU128Decoder = (config: NumberCodecConfig = {}): FixedSizeDecoder<bigint, 16> =>
+    numberDecoderFactory({
+        config,
+        get: (view, le) => {
+            const leftOffset = le ? 8 : 0;
+            const rightOffset = le ? 0 : 8;
+            const left = view.getBigUint64(leftOffset, le);
+            const right = view.getBigUint64(rightOffset, le);
+            return (left << 64n) + right;
+        },
+        name: 'u128',
+        size: 16,
+    });
+
+/**
+ * Returns a codec for encoding and decoding 128-bit unsigned integers (`u128`).
+ *
+ * This codec serializes `u128` values using 16 bytes.
+ * Values can be provided as either `number` or `bigint`, but the decoded value is always a `bigint`.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeCodec<number | bigint, bigint, 16>` for encoding and decoding `u128` values.
+ *
+ * @example
+ * Encoding and decoding a `u128` value.
+ * ```ts
+ * const codec = getU128Codec();
+ * const bytes = codec.encode(42); // 0x2a000000000000000000000000000000
+ * const value = codec.decode(bytes); // 42n
+ * ```
+ *
+ * @example
+ * Using big-endian encoding.
+ * ```ts
+ * const codec = getU128Codec({ endian: Endian.Big });
+ * const bytes = codec.encode(42); // 0x0000000000000000000000000000002a
+ * ```
+ *
+ * @remarks
+ * This codec supports values between `0` and `2^128 - 1`.
+ * Since JavaScript `number` cannot safely represent values beyond `2^53 - 1`, the decoded value is always a `bigint`.
+ *
+ * - If you need a smaller unsigned integer, consider using {@link getU64Codec} or {@link getU32Codec}.
+ * - If you need signed integers, consider using {@link getI128Codec}.
+ *
+ * Separate {@link getU128Encoder} and {@link getU128Decoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getU128Encoder().encode(42);
+ * const value = getU128Decoder().decode(bytes);
+ * ```
+ *
+ * @see {@link getU128Encoder}
+ * @see {@link getU128Decoder}
+ */
+export const getU128Codec = (config: NumberCodecConfig = {}): FixedSizeCodec<bigint | number, bigint, 16> =>
+    combineCodec(getU128Encoder(config), getU128Decoder(config));