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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/codecs-numbers",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313112147",
   "description": "Codecs for numbers of different sizes and endianness",
   "homepage": "https://www.solanakit.com/api#solanacodecs-numbers",
   "exports": {
@@ -33,7 +33,8 @@
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -55,8 +56,8 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/codecs-core": "6.3.1",
-    "@solana/errors": "6.3.1"
+    "@solana/codecs-core": "6.3.2-canary-20260313112147",
+    "@solana/errors": "6.3.2-canary-20260313112147"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/assertions.ts

@@ -0,0 +1,42 @@
+import { SOLANA_ERROR__CODECS__NUMBER_OUT_OF_RANGE, SolanaError } from '@solana/errors';
+
+/**
+ * Ensures that a given number falls within a specified range.
+ *
+ * If the number is outside the allowed range, an error is thrown.
+ * This function is primarily used to validate values before encoding them in a codec.
+ *
+ * @param codecDescription - A string describing the codec that is performing the validation.
+ * @param min - The minimum allowed value (inclusive).
+ * @param max - The maximum allowed value (inclusive).
+ * @param value - The number to validate.
+ *
+ * @throws {@link SolanaError} if the value is out of range.
+ *
+ * @example
+ * Validating a number within range.
+ * ```ts
+ * assertNumberIsBetweenForCodec('u8', 0, 255, 42); // Passes
+ * ```
+ *
+ * @example
+ * Throwing an error for an out-of-range value.
+ * ```ts
+ * assertNumberIsBetweenForCodec('u8', 0, 255, 300); // Throws
+ * ```
+ */
+export function assertNumberIsBetweenForCodec(
+    codecDescription: string,
+    min: bigint | number,
+    max: bigint | number,
+    value: bigint | number,
+) {
+    if (value < min || value > max) {
+        throw new SolanaError(SOLANA_ERROR__CODECS__NUMBER_OUT_OF_RANGE, {
+            codecDescription,
+            max,
+            min,
+            value,
+        });
+    }
+}

package/src/common.ts

@@ -0,0 +1,94 @@
+import { Codec, Decoder, Encoder, FixedSizeCodec, FixedSizeDecoder, FixedSizeEncoder } from '@solana/codecs-core';
+/**
+ * Represents an encoder for numbers and bigints.
+ *
+ * This type allows encoding values that are either `number` or `bigint`.
+ * Depending on the specific implementation, the encoded output may have a fixed or variable size.
+ *
+ * @see {@link FixedSizeNumberEncoder}
+ */
+export type NumberEncoder = Encoder<bigint | number>;
+
+/**
+ * Represents a fixed-size encoder for numbers and bigints.
+ *
+ * This encoder serializes values using an exact number of bytes, defined by `TSize`.
+ *
+ * @typeParam TSize - The number of bytes used for encoding.
+ *
+ * @see {@link NumberEncoder}
+ */
+export type FixedSizeNumberEncoder<TSize extends number = number> = FixedSizeEncoder<bigint | number, TSize>;
+
+/**
+ * Represents a decoder for numbers and bigints.
+ *
+ * This type supports decoding values as either `number` or `bigint`, depending on the implementation.
+ *
+ * @see {@link FixedSizeNumberDecoder}
+ */
+export type NumberDecoder = Decoder<bigint> | Decoder<number>;
+
+/**
+ * Represents a fixed-size decoder for numbers and bigints.
+ *
+ * This decoder reads a fixed number of bytes (`TSize`) and converts them into a `number` or `bigint`.
+ *
+ * @typeParam TSize - The number of bytes expected for decoding.
+ *
+ * @see {@link NumberDecoder}
+ */
+export type FixedSizeNumberDecoder<TSize extends number = number> =
+    | FixedSizeDecoder<bigint, TSize>
+    | FixedSizeDecoder<number, TSize>;
+
+/**
+ * Represents a codec for encoding and decoding numbers and bigints.
+ *
+ * - The encoded value can be either a `number` or a `bigint`.
+ * - The decoded value will always be either a `number` or `bigint`, depending on the implementation.
+ *
+ * @see {@link FixedSizeNumberCodec}
+ */
+export type NumberCodec = Codec<bigint | number, bigint> | Codec<bigint | number, number>;
+
+/**
+ * Represents a fixed-size codec for encoding and decoding numbers and bigints.
+ *
+ * This codec uses a specific number of bytes (`TSize`) for serialization.
+ * The encoded value can be either a `number` or `bigint`, but the decoded value will always be a `number` or `bigint`,
+ * depending on the implementation.
+ *
+ * @typeParam TSize - The number of bytes used for encoding and decoding.
+ *
+ * @see {@link NumberCodec}
+ */
+export type FixedSizeNumberCodec<TSize extends number = number> =
+    | FixedSizeCodec<bigint | number, bigint, TSize>
+    | FixedSizeCodec<bigint | number, number, TSize>;
+
+/**
+ * Configuration options for number codecs that use more than one byte.
+ *
+ * This configuration applies to all number codecs except `u8` and `i8`,
+ * allowing the user to specify the endianness of serialization.
+ */
+export type NumberCodecConfig = {
+    /**
+     * Specifies whether numbers should be encoded in little-endian or big-endian format.
+     *
+     * @defaultValue `Endian.Little`
+     */
+    endian?: Endian;
+};
+
+/**
+ * Defines the byte order used for number serialization.
+ *
+ * - `Little`: The least significant byte is stored first.
+ * - `Big`: The most significant byte is stored first.
+ */
+export enum Endian {
+    Little,
+    Big,
+}

package/src/f32.ts

@@ -0,0 +1,104 @@
+import { combineCodec, FixedSizeCodec, FixedSizeDecoder, FixedSizeEncoder } from '@solana/codecs-core';
+
+import { NumberCodecConfig } from './common';
+import { numberDecoderFactory, numberEncoderFactory } from './utils';
+
+/**
+ * Returns an encoder for 32-bit floating-point numbers (`f32`).
+ *
+ * This encoder serializes `f32` values using 4 bytes.
+ * Floating-point values may lose precision when encoded.
+ *
+ * For more details, see {@link getF32Codec}.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeEncoder<number, 4>` for encoding `f32` values.
+ *
+ * @example
+ * Encoding an `f32` value.
+ * ```ts
+ * const encoder = getF32Encoder();
+ * const bytes = encoder.encode(-1.5); // 0x0000c0bf
+ * ```
+ *
+ * @see {@link getF32Codec}
+ */
+export const getF32Encoder = (config: NumberCodecConfig = {}): FixedSizeEncoder<bigint | number, 4> =>
+    numberEncoderFactory({
+        config,
+        name: 'f32',
+        set: (view, value, le) => view.setFloat32(0, Number(value), le),
+        size: 4,
+    });
+
+/**
+ * Returns a decoder for 32-bit floating-point numbers (`f32`).
+ *
+ * This decoder deserializes `f32` values from 4 bytes.
+ * Some precision may be lost during decoding due to floating-point representation.
+ *
+ * For more details, see {@link getF32Codec}.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeDecoder<number, 4>` for decoding `f32` values.
+ *
+ * @example
+ * Decoding an `f32` value.
+ * ```ts
+ * const decoder = getF32Decoder();
+ * const value = decoder.decode(new Uint8Array([0x00, 0x00, 0xc0, 0xbf])); // -1.5
+ * ```
+ *
+ * @see {@link getF32Codec}
+ */
+export const getF32Decoder = (config: NumberCodecConfig = {}): FixedSizeDecoder<number, 4> =>
+    numberDecoderFactory({
+        config,
+        get: (view, le) => view.getFloat32(0, le),
+        name: 'f32',
+        size: 4,
+    });
+
+/**
+ * Returns a codec for encoding and decoding 32-bit floating-point numbers (`f32`).
+ *
+ * This codec serializes `f32` values using 4 bytes.
+ * Due to the IEEE 754 floating-point representation, some precision loss may occur.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeCodec<number, number, 4>` for encoding and decoding `f32` values.
+ *
+ * @example
+ * Encoding and decoding an `f32` value.
+ * ```ts
+ * const codec = getF32Codec();
+ * const bytes = codec.encode(-1.5); // 0x0000c0bf
+ * const value = codec.decode(bytes); // -1.5
+ * ```
+ *
+ * @example
+ * Using big-endian encoding.
+ * ```ts
+ * const codec = getF32Codec({ endian: Endian.Big });
+ * const bytes = codec.encode(-1.5); // 0xbfc00000
+ * ```
+ *
+ * @remarks
+ * `f32` values follow the IEEE 754 single-precision floating-point standard.
+ * Precision loss may occur for certain values.
+ *
+ * - If you need higher precision, consider using {@link getF64Codec}.
+ * - If you need integer values, consider using {@link getI32Codec} or {@link getU32Codec}.
+ *
+ * Separate {@link getF32Encoder} and {@link getF32Decoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getF32Encoder().encode(-1.5);
+ * const value = getF32Decoder().decode(bytes);
+ * ```
+ *
+ * @see {@link getF32Encoder}
+ * @see {@link getF32Decoder}
+ */
+export const getF32Codec = (config: NumberCodecConfig = {}): FixedSizeCodec<bigint | number, number, 4> =>
+    combineCodec(getF32Encoder(config), getF32Decoder(config));

package/src/f64.ts

@@ -0,0 +1,104 @@
+import { combineCodec, FixedSizeCodec, FixedSizeDecoder, FixedSizeEncoder } from '@solana/codecs-core';
+
+import { NumberCodecConfig } from './common';
+import { numberDecoderFactory, numberEncoderFactory } from './utils';
+
+/**
+ * Returns an encoder for 64-bit floating-point numbers (`f64`).
+ *
+ * This encoder serializes `f64` values using 8 bytes.
+ * Floating-point values may lose precision when encoded.
+ *
+ * For more details, see {@link getF64Codec}.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeEncoder<number, 8>` for encoding `f64` values.
+ *
+ * @example
+ * Encoding an `f64` value.
+ * ```ts
+ * const encoder = getF64Encoder();
+ * const bytes = encoder.encode(-1.5); // 0x000000000000f8bf
+ * ```
+ *
+ * @see {@link getF64Codec}
+ */
+export const getF64Encoder = (config: NumberCodecConfig = {}): FixedSizeEncoder<bigint | number, 8> =>
+    numberEncoderFactory({
+        config,
+        name: 'f64',
+        set: (view, value, le) => view.setFloat64(0, Number(value), le),
+        size: 8,
+    });
+
+/**
+ * Returns a decoder for 64-bit floating-point numbers (`f64`).
+ *
+ * This decoder deserializes `f64` values from 8 bytes.
+ * Some precision may be lost during decoding due to floating-point representation.
+ *
+ * For more details, see {@link getF64Codec}.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeDecoder<number, 8>` for decoding `f64` values.
+ *
+ * @example
+ * Decoding an `f64` value.
+ * ```ts
+ * const decoder = getF64Decoder();
+ * const value = decoder.decode(new Uint8Array([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xf8, 0xbf])); // -1.5
+ * ```
+ *
+ * @see {@link getF64Codec}
+ */
+export const getF64Decoder = (config: NumberCodecConfig = {}): FixedSizeDecoder<number, 8> =>
+    numberDecoderFactory({
+        config,
+        get: (view, le) => view.getFloat64(0, le),
+        name: 'f64',
+        size: 8,
+    });
+
+/**
+ * Returns a codec for encoding and decoding 64-bit floating-point numbers (`f64`).
+ *
+ * This codec serializes `f64` values using 8 bytes.
+ * Due to the IEEE 754 floating-point representation, some precision loss may occur.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeCodec<number, number, 8>` for encoding and decoding `f64` values.
+ *
+ * @example
+ * Encoding and decoding an `f64` value.
+ * ```ts
+ * const codec = getF64Codec();
+ * const bytes = codec.encode(-1.5); // 0x000000000000f8bf
+ * const value = codec.decode(bytes); // -1.5
+ * ```
+ *
+ * @example
+ * Using big-endian encoding.
+ * ```ts
+ * const codec = getF64Codec({ endian: Endian.Big });
+ * const bytes = codec.encode(-1.5); // 0xbff8000000000000
+ * ```
+ *
+ * @remarks
+ * `f64` values follow the IEEE 754 double-precision floating-point standard.
+ * Precision loss may still occur but is significantly lower than `f32`.
+ *
+ * - If you need smaller floating-point values, consider using {@link getF32Codec}.
+ * - If you need integer values, consider using {@link getI64Codec} or {@link getU64Codec}.
+ *
+ * Separate {@link getF64Encoder} and {@link getF64Decoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getF64Encoder().encode(-1.5);
+ * const value = getF64Decoder().decode(bytes);
+ * ```
+ *
+ * @see {@link getF64Encoder}
+ * @see {@link getF64Decoder}
+ */
+export const getF64Codec = (config: NumberCodecConfig = {}): FixedSizeCodec<bigint | number, number, 8> =>
+    combineCodec(getF64Encoder(config), getF64Decoder(config));

package/src/i128.ts

@@ -0,0 +1,121 @@
+import { combineCodec, FixedSizeCodec, FixedSizeDecoder, FixedSizeEncoder } from '@solana/codecs-core';
+
+import { NumberCodecConfig } from './common';
+import { numberDecoderFactory, numberEncoderFactory } from './utils';
+
+/**
+ * Returns an encoder for 128-bit signed integers (`i128`).
+ *
+ * This encoder serializes `i128` values using 16 bytes.
+ * Values can be provided as either `number` or `bigint`.
+ *
+ * For more details, see {@link getI128Codec}.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeEncoder<number | bigint, 16>` for encoding `i128` values.
+ *
+ * @example
+ * Encoding an `i128` value.
+ * ```ts
+ * const encoder = getI128Encoder();
+ * const bytes = encoder.encode(-42n); // 0xd6ffffffffffffffffffffffffffffff
+ * ```
+ *
+ * @see {@link getI128Codec}
+ */
+export const getI128Encoder = (config: NumberCodecConfig = {}): FixedSizeEncoder<bigint | number, 16> =>
+    numberEncoderFactory({
+        config,
+        name: 'i128',
+        range: [-BigInt('0x7fffffffffffffffffffffffffffffff') - 1n, BigInt('0x7fffffffffffffffffffffffffffffff')],
+        set: (view, value, le) => {
+            const leftOffset = le ? 8 : 0;
+            const rightOffset = le ? 0 : 8;
+            const rightMask = 0xffffffffffffffffn;
+            view.setBigInt64(leftOffset, BigInt(value) >> 64n, le);
+            view.setBigUint64(rightOffset, BigInt(value) & rightMask, le);
+        },
+        size: 16,
+    });
+
+/**
+ * Returns a decoder for 128-bit signed integers (`i128`).
+ *
+ * This decoder deserializes `i128` values from 16 bytes.
+ * The decoded value is always a `bigint`.
+ *
+ * For more details, see {@link getI128Codec}.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeDecoder<bigint, 16>` for decoding `i128` values.
+ *
+ * @example
+ * Decoding an `i128` value.
+ * ```ts
+ * const decoder = getI128Decoder();
+ * const value = decoder.decode(new Uint8Array([
+ *   0xd6, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
+ *   0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff
+ * ])); // -42n
+ * ```
+ *
+ * @see {@link getI128Codec}
+ */
+export const getI128Decoder = (config: NumberCodecConfig = {}): FixedSizeDecoder<bigint, 16> =>
+    numberDecoderFactory({
+        config,
+        get: (view, le) => {
+            const leftOffset = le ? 8 : 0;
+            const rightOffset = le ? 0 : 8;
+            const left = view.getBigInt64(leftOffset, le);
+            const right = view.getBigUint64(rightOffset, le);
+            return (left << 64n) + right;
+        },
+        name: 'i128',
+        size: 16,
+    });
+
+/**
+ * Returns a codec for encoding and decoding 128-bit signed integers (`i128`).
+ *
+ * This codec serializes `i128` 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 `i128` values.
+ *
+ * @example
+ * Encoding and decoding an `i128` value.
+ * ```ts
+ * const codec = getI128Codec();
+ * const bytes = codec.encode(-42n); // 0xd6ffffffffffffffffffffffffffffff
+ * const value = codec.decode(bytes); // -42n
+ * ```
+ *
+ * @example
+ * Using big-endian encoding.
+ * ```ts
+ * const codec = getI128Codec({ endian: Endian.Big });
+ * const bytes = codec.encode(-42n); // 0xffffffffffffffffffffffffffffd6
+ * ```
+ *
+ * @remarks
+ * This codec supports values between `-2^127` and `2^127 - 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 getI64Codec} or {@link getI32Codec}.
+ * - If you need a larger signed integer, consider using a custom codec.
+ * - If you need unsigned integers, consider using {@link getU128Codec}.
+ *
+ * Separate {@link getI128Encoder} and {@link getI128Decoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getI128Encoder().encode(-42);
+ * const value = getI128Decoder().decode(bytes);
+ * ```
+ *
+ * @see {@link getI128Encoder}
+ * @see {@link getI128Decoder}
+ */
+export const getI128Codec = (config: NumberCodecConfig = {}): FixedSizeCodec<bigint | number, bigint, 16> =>
+    combineCodec(getI128Encoder(config), getI128Decoder(config));

package/src/i16.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 16-bit signed integers (`i16`).
+ *
+ * This encoder serializes `i16` values using 2 bytes.
+ * Values can be provided as either `number` or `bigint`.
+ *
+ * For more details, see {@link getI16Codec}.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeEncoder<number | bigint, 2>` for encoding `i16` values.
+ *
+ * @example
+ * Encoding an `i16` value.
+ * ```ts
+ * const encoder = getI16Encoder();
+ * const bytes = encoder.encode(-42); // 0xd6ff
+ * ```
+ *
+ * @see {@link getI16Codec}
+ */
+export const getI16Encoder = (config: NumberCodecConfig = {}): FixedSizeEncoder<bigint | number, 2> =>
+    numberEncoderFactory({
+        config,
+        name: 'i16',
+        range: [-Number('0x7fff') - 1, Number('0x7fff')],
+        set: (view, value, le) => view.setInt16(0, Number(value), le),
+        size: 2,
+    });
+
+/**
+ * Returns a decoder for 16-bit signed integers (`i16`).
+ *
+ * This decoder deserializes `i16` values from 2 bytes.
+ * The decoded value is always a `number`.
+ *
+ * For more details, see {@link getI16Codec}.
+ *
+ * @param config - Optional configuration to specify endianness (little by default).
+ * @returns A `FixedSizeDecoder<number, 2>` for decoding `i16` values.
+ *
+ * @example
+ * Decoding an `i16` value.
+ * ```ts
+ * const decoder = getI16Decoder();
+ * const value = decoder.decode(new Uint8Array([0xd6, 0xff])); // -42
+ * ```
+ *
+ * @see {@link getI16Codec}
+ */
+export const getI16Decoder = (config: NumberCodecConfig = {}): FixedSizeDecoder<number, 2> =>
+    numberDecoderFactory({
+        config,
+        get: (view, le) => view.getInt16(0, le),
+        name: 'i16',
+        size: 2,
+    });
+
+/**
+ * Returns a codec for encoding and decoding 16-bit signed integers (`i16`).
+ *
+ * This codec serializes `i16` values using 2 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, 2>` for encoding and decoding `i16` values.
+ *
+ * @example
+ * Encoding and decoding an `i16` value.
+ * ```ts
+ * const codec = getI16Codec();
+ * const bytes = codec.encode(-42); // 0xd6ff
+ * const value = codec.decode(bytes); // -42
+ * ```
+ *
+ * @example
+ * Using big-endian encoding.
+ * ```ts
+ * const codec = getI16Codec({ endian: Endian.Big });
+ * const bytes = codec.encode(-42); // 0xffd6
+ * ```
+ *
+ * @remarks
+ * This codec supports values between `-2^15` (`-32,768`) and `2^15 - 1` (`32,767`).
+ *
+ * - If you need a smaller signed integer, consider using {@link getI8Codec}.
+ * - If you need a larger signed integer, consider using {@link getI32Codec}.
+ * - If you need unsigned integers, consider using {@link getU16Codec}.
+ *
+ * Separate {@link getI16Encoder} and {@link getI16Decoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getI16Encoder().encode(-42);
+ * const value = getI16Decoder().decode(bytes);
+ * ```
+ *
+ * @see {@link getI16Encoder}
+ * @see {@link getI16Decoder}
+ */
+export const getI16Codec = (config: NumberCodecConfig = {}): FixedSizeCodec<bigint | number, number, 2> =>
+    combineCodec(getI16Encoder(config), getI16Decoder(config));