@solana/codecs-numbers 2.0.0-experimental.ff8c65b → 2.0.0-preview.1

package/README.md

@@ -16,10 +16,118 @@
 
 This package contains codecs for numbers of different sizes and endianness. It can be used standalone, but it is also exported as part of the Solana JavaScript SDK [`@solana/web3.js@experimental`](https://github.com/solana-labs/solana-web3.js/tree/master/packages/library).
 
-## Types
+This package is also part of the [`@solana/codecs` package](https://github.com/solana-labs/solana-web3.js/tree/master/packages/codecs) which acts as an entry point for all codec packages as well as for their documentation.
 
-TODO
+## Integer codecs
 
-## Functions
+This package provides ten codecs of five different byte sizes for integers. Five of them store unsigned integers and the other five store signed integers.
 
-TODO
+```ts
+// Unsigned integers.
+getU8Codec().encode(42); // 0x2a
+getU16Codec().encode(42); // 0x2a00
+getU32Codec().encode(42); // 0x2a000000
+getU64Codec().encode(42); // 0x2a00000000000000
+getU128Codec().encode(42); // 0x2a000000000000000000000000000000
+
+// Signed integers.
+getI8Codec().encode(-42); // 0xd6
+getI16Codec().encode(-42); // 0xd6ff
+getI32Codec().encode(-42); // 0xd6ffffff
+getI64Codec().encode(-42); // 0xd6ffffffffffffff
+getI128Codec().encode(-42); // 0xd6ffffffffffffffffffffffffffffff
+```
+
+By default, integers are stored using little endianness but you may change this behaviour via the `endian` option. This option is available for every codec that uses more than a single byte.
+
+```ts
+// Big-endian unsigned integers.
+getU16Codec({ endian: Endian.BIG }).encode(42); // 0x002a
+getU32Codec({ endian: Endian.BIG }).encode(42); // 0x0000002a
+getU64Codec({ endian: Endian.BIG }).encode(42); // 0x000000000000002a
+getU128Codec({ endian: Endian.BIG }).encode(42); // 0x0000000000000000000000000000002a
+
+// Big-endian signed integers.
+getI16Codec({ endian: Endian.BIG }).encode(-42); // 0xffd6
+getI32Codec({ endian: Endian.BIG }).encode(-42); // 0xffffffd6
+getI64Codec({ endian: Endian.BIG }).encode(-42); // 0xffffffffffffffd6
+getI128Codec({ endian: Endian.BIG }).encode(-42); // 0xffffffffffffffffffffffffffffffd6
+```
+
+All integer codecs are of type `Codec<number>` except for the `u64`, `u128`, `i64` and `i128` codecs which are of type `Codec<number | bigint, bigint>`. This means we can provide either a `number` of a `bigint` value to encode but the decoded value will always be a `bigint`. This is because JavaScript's native `number` type does not support numbers larger than `2^53 - 1` and these large integer codecs have the potential to go over that value.
+
+```ts
+const bytesFromNumber = getU64Codec().encode(42);
+getU64Codec().decode(bytesFromNumber); // BigInt(42)
+
+// OR
+const bytesFromBigInt = getU64Codec().encode(BigInt(42));
+getU64Codec().decode(bytesFromBigInt); // BigInt(42)
+```
+
+Finally, for each of these `get*Codec` functions, separate `get*Encoder` and `get*Decoder` functions exist to focus on only one side of the serialization and tree-shake the rest of the functions away.
+
+```ts
+const bytes = getU8Encoder().encode(42);
+const value = getU8Decoder().decode(bytes);
+```
+
+## Decimal number codecs
+
+This package also provides two codecs for floating numbers. One using 32 bits and one using 64 bits.
+
+```ts
+getF32Codec().encode(-1.5); // 0x0000c0bf
+getF64Codec().encode(-1.5); // 0x000000000000f8bf
+```
+
+Similarly to the integer codecs, they are stored in little-endian by default but may be stored in big-endian using the `endian` option.
+
+```ts
+getF32Codec({ endian: Endian.BIG }).encode(-1.5); // 0xbfc00000
+getF64Codec({ endian: Endian.BIG }).encode(-1.5); // 0xbff8000000000000
+```
+
+Note that based on the selected codec, some of the precision of the number you are encoding may be lost when decoding it. For instance, when storing `3.1415` using a `f32` codec, you will not get the exact same number back.
+
+```ts
+const bytes = getF32Codec().encode(3.1415); // 0x560e4940
+const value = getF32Codec().decode(bytes); // 3.1414999961853027 !== 3.1415
+```
+
+As usual, separate encoder and decoder functions are available for these codecs.
+
+```ts
+getF32Encoder().encode(-1.5);
+getF32Decoder().decode(new Uint8Array([...]));
+
+getF64Encoder().encode(-1.5);
+getF64Decoder().decode(new Uint8Array([...]));
+```
+
+## Short u16 codec
+
+This last integer codec is less common `VariableSizeCodec` that stores an unsigned integer using between 1 to 3 bytes depending on the value of that integer.
+
+```ts
+const bytes = getShortU16Codec().encode(42); // 0x2a
+const value = getShortU16Codec().decode(bytes); // 42
+```
+
+If the provided integer is equal to or lower than `0x7f`, it will be stored as-is, using a single byte. However, if the integer is above `0x7f`, then the top bit is set and the remaining value is stored in the next bytes. Each byte follows the same pattern until the third byte. The third byte, if needed, uses all 8 bits to store the last byte of the original value.
+
+In other words, this codec provides an extendable size that adapts based on the integer. In the illustration below, you can see the `0` and `1` byte flags for each scenario as well as the available bits to store the integer marked with `X`.
+
+```
+0XXXXXXX <- From 0 to 127.
+1XXXXXXX 0XXXXXXX <- From 128 to 16,383.
+1XXXXXXX 1XXXXXXX XXXXXXXX <- From 16,384 to 4,194,303.
+```
+
+This codec is mainly used internally when encoding and decoding Solana transactions.
+
+Separate encoder and decoder functions are also available via `getShortU16Encoder` and `getShortU16Decoder` respectively.
+
+---
+
+To read more about the available codecs and how to use them, check out the documentation of the main [`@solana/codecs` package](https://github.com/solana-labs/solana-web3.js/tree/master/packages/codecs).

package/dist/index.browser.cjs

@@ -1,13 +1,17 @@
 'use strict';
 
+var errors = require('@solana/errors');
 var codecsCore = require('@solana/codecs-core');
 
 // src/assertions.ts
 function assertNumberIsBetweenForCodec(codecDescription, min, max, value) {
   if (value < min || value > max) {
-    throw new Error(
-      `Codec [${codecDescription}] expected number to be in the range [${min}, ${max}], got ${value}.`
-    );
+    throw new errors.SolanaError(errors.SOLANA_ERROR__CODECS__NUMBER_OUT_OF_RANGE, {
+      codecDescription,
+      max,
+      min,
+      value
+    });
   }
 }
 
@@ -17,49 +21,33 @@ var Endian = /* @__PURE__ */ ((Endian2) => {
   Endian2[Endian2["BIG"] = 1] = "BIG";
   return Endian2;
 })(Endian || {});
-function sharedNumberFactory(input) {
-  let littleEndian;
-  let defaultDescription = input.name;
-  if (input.size > 1) {
-    littleEndian = !("endian" in input.options) || input.options.endian === 0 /* LITTLE */;
-    defaultDescription += littleEndian ? "(le)" : "(be)";
-  }
-  return {
-    description: input.options.description ?? defaultDescription,
-    fixedSize: input.size,
-    littleEndian,
-    maxSize: input.size
-  };
+function isLittleEndian(config) {
+  return config?.endian === 1 /* BIG */ ? false : true;
 }
 function numberEncoderFactory(input) {
-  const codecData = sharedNumberFactory(input);
-  return {
-    description: codecData.description,
-    encode(value) {
+  return codecsCore.createEncoder({
+    fixedSize: input.size,
+    write(value, bytes, offset) {
       if (input.range) {
         assertNumberIsBetweenForCodec(input.name, input.range[0], input.range[1], value);
       }
       const arrayBuffer = new ArrayBuffer(input.size);
-      input.set(new DataView(arrayBuffer), value, codecData.littleEndian);
-      return new Uint8Array(arrayBuffer);
-    },
-    fixedSize: codecData.fixedSize,
-    maxSize: codecData.maxSize
-  };
+      input.set(new DataView(arrayBuffer), value, isLittleEndian(input.config));
+      bytes.set(new Uint8Array(arrayBuffer), offset);
+      return offset + input.size;
+    }
+  });
 }
 function numberDecoderFactory(input) {
-  const codecData = sharedNumberFactory(input);
-  return {
-    decode(bytes, offset = 0) {
-      codecsCore.assertByteArrayIsNotEmptyForCodec(codecData.description, bytes, offset);
-      codecsCore.assertByteArrayHasEnoughBytesForCodec(codecData.description, input.size, bytes, offset);
+  return codecsCore.createDecoder({
+    fixedSize: input.size,
+    read(bytes, offset = 0) {
+      codecsCore.assertByteArrayIsNotEmptyForCodec(input.name, bytes, offset);
+      codecsCore.assertByteArrayHasEnoughBytesForCodec(input.name, input.size, bytes, offset);
       const view = new DataView(toArrayBuffer(bytes, offset, input.size));
-      return [input.get(view, codecData.littleEndian), offset + input.size];
-    },
-    description: codecData.description,
-    fixedSize: codecData.fixedSize,
-    maxSize: codecData.maxSize
-  };
+      return [input.get(view, isLittleEndian(input.config)), offset + input.size];
+    }
+  });
 }
 function toArrayBuffer(bytes, offset, length) {
   const bytesOffset = bytes.byteOffset + (offset ?? 0);
@@ -68,35 +56,35 @@ function toArrayBuffer(bytes, offset, length) {
 }
 
 // src/f32.ts
-var getF32Encoder = (options = {}) => numberEncoderFactory({
+var getF32Encoder = (config = {}) => numberEncoderFactory({
+  config,
   name: "f32",
-  options,
   set: (view, value, le) => view.setFloat32(0, value, le),
   size: 4
 });
-var getF32Decoder = (options = {}) => numberDecoderFactory({
+var getF32Decoder = (config = {}) => numberDecoderFactory({
+  config,
   get: (view, le) => view.getFloat32(0, le),
   name: "f32",
-  options,
   size: 4
 });
-var getF32Codec = (options = {}) => codecsCore.combineCodec(getF32Encoder(options), getF32Decoder(options));
-var getF64Encoder = (options = {}) => numberEncoderFactory({
+var getF32Codec = (config = {}) => codecsCore.combineCodec(getF32Encoder(config), getF32Decoder(config));
+var getF64Encoder = (config = {}) => numberEncoderFactory({
+  config,
   name: "f64",
-  options,
   set: (view, value, le) => view.setFloat64(0, value, le),
   size: 8
 });
-var getF64Decoder = (options = {}) => numberDecoderFactory({
+var getF64Decoder = (config = {}) => numberDecoderFactory({
+  config,
   get: (view, le) => view.getFloat64(0, le),
   name: "f64",
-  options,
   size: 8
 });
-var getF64Codec = (options = {}) => codecsCore.combineCodec(getF64Encoder(options), getF64Decoder(options));
-var getI128Encoder = (options = {}) => numberEncoderFactory({
+var getF64Codec = (config = {}) => codecsCore.combineCodec(getF64Encoder(config), getF64Decoder(config));
+var getI128Encoder = (config = {}) => numberEncoderFactory({
+  config,
   name: "i128",
-  options,
   range: [-BigInt("0x7fffffffffffffffffffffffffffffff") - 1n, BigInt("0x7fffffffffffffffffffffffffffffff")],
   set: (view, value, le) => {
     const leftOffset = le ? 8 : 0;
@@ -107,7 +95,8 @@ var getI128Encoder = (options = {}) => numberEncoderFactory({
   },
   size: 16
 });
-var getI128Decoder = (options = {}) => numberDecoderFactory({
+var getI128Decoder = (config = {}) => numberDecoderFactory({
+  config,
   get: (view, le) => {
     const leftOffset = le ? 8 : 0;
     const rightOffset = le ? 0 : 8;
@@ -116,89 +105,93 @@ var getI128Decoder = (options = {}) => numberDecoderFactory({
     return (left << 64n) + right;
   },
   name: "i128",
-  options,
   size: 16
 });
-var getI128Codec = (options = {}) => codecsCore.combineCodec(getI128Encoder(options), getI128Decoder(options));
-var getI16Encoder = (options = {}) => numberEncoderFactory({
+var getI128Codec = (config = {}) => codecsCore.combineCodec(getI128Encoder(config), getI128Decoder(config));
+var getI16Encoder = (config = {}) => numberEncoderFactory({
+  config,
   name: "i16",
-  options,
   range: [-Number("0x7fff") - 1, Number("0x7fff")],
   set: (view, value, le) => view.setInt16(0, value, le),
   size: 2
 });
-var getI16Decoder = (options = {}) => numberDecoderFactory({
+var getI16Decoder = (config = {}) => numberDecoderFactory({
+  config,
   get: (view, le) => view.getInt16(0, le),
   name: "i16",
-  options,
   size: 2
 });
-var getI16Codec = (options = {}) => codecsCore.combineCodec(getI16Encoder(options), getI16Decoder(options));
-var getI32Encoder = (options = {}) => numberEncoderFactory({
+var getI16Codec = (config = {}) => codecsCore.combineCodec(getI16Encoder(config), getI16Decoder(config));
+var getI32Encoder = (config = {}) => numberEncoderFactory({
+  config,
   name: "i32",
-  options,
   range: [-Number("0x7fffffff") - 1, Number("0x7fffffff")],
   set: (view, value, le) => view.setInt32(0, value, le),
   size: 4
 });
-var getI32Decoder = (options = {}) => numberDecoderFactory({
+var getI32Decoder = (config = {}) => numberDecoderFactory({
+  config,
   get: (view, le) => view.getInt32(0, le),
   name: "i32",
-  options,
   size: 4
 });
-var getI32Codec = (options = {}) => codecsCore.combineCodec(getI32Encoder(options), getI32Decoder(options));
-var getI64Encoder = (options = {}) => numberEncoderFactory({
+var getI32Codec = (config = {}) => codecsCore.combineCodec(getI32Encoder(config), getI32Decoder(config));
+var getI64Encoder = (config = {}) => numberEncoderFactory({
+  config,
   name: "i64",
-  options,
   range: [-BigInt("0x7fffffffffffffff") - 1n, BigInt("0x7fffffffffffffff")],
   set: (view, value, le) => view.setBigInt64(0, BigInt(value), le),
   size: 8
 });
-var getI64Decoder = (options = {}) => numberDecoderFactory({
+var getI64Decoder = (config = {}) => numberDecoderFactory({
+  config,
   get: (view, le) => view.getBigInt64(0, le),
   name: "i64",
-  options,
   size: 8
 });
-var getI64Codec = (options = {}) => codecsCore.combineCodec(getI64Encoder(options), getI64Decoder(options));
-var getI8Encoder = (options = {}) => numberEncoderFactory({
+var getI64Codec = (config = {}) => codecsCore.combineCodec(getI64Encoder(config), getI64Decoder(config));
+var getI8Encoder = () => numberEncoderFactory({
   name: "i8",
-  options,
   range: [-Number("0x7f") - 1, Number("0x7f")],
   set: (view, value) => view.setInt8(0, value),
   size: 1
 });
-var getI8Decoder = (options = {}) => numberDecoderFactory({
+var getI8Decoder = () => numberDecoderFactory({
   get: (view) => view.getInt8(0),
   name: "i8",
-  options,
   size: 1
 });
-var getI8Codec = (options = {}) => codecsCore.combineCodec(getI8Encoder(options), getI8Decoder(options));
-var getShortU16Encoder = (options = {}) => ({
-  description: options.description ?? "shortU16",
-  encode: (value) => {
+var getI8Codec = () => codecsCore.combineCodec(getI8Encoder(), getI8Decoder());
+var getShortU16Encoder = () => codecsCore.createEncoder({
+  getSizeFromValue: (value) => {
+    if (value <= 127)
+      return 1;
+    if (value <= 16383)
+      return 2;
+    return 3;
+  },
+  maxSize: 3,
+  write: (value, bytes, offset) => {
     assertNumberIsBetweenForCodec("shortU16", 0, 65535, value);
-    const bytes = [0];
+    const shortU16Bytes = [0];
     for (let ii = 0; ; ii += 1) {
       const alignedValue = value >> ii * 7;
       if (alignedValue === 0) {
         break;
       }
       const nextSevenBits = 127 & alignedValue;
-      bytes[ii] = nextSevenBits;
+      shortU16Bytes[ii] = nextSevenBits;
       if (ii > 0) {
-        bytes[ii - 1] |= 128;
+        shortU16Bytes[ii - 1] |= 128;
       }
     }
-    return new Uint8Array(bytes);
-  },
-  fixedSize: null,
-  maxSize: 3
+    bytes.set(shortU16Bytes, offset);
+    return offset + shortU16Bytes.length;
+  }
 });
-var getShortU16Decoder = (options = {}) => ({
-  decode: (bytes, offset = 0) => {
+var getShortU16Decoder = () => codecsCore.createDecoder({
+  maxSize: 3,
+  read: (bytes, offset) => {
     let value = 0;
     let byteCount = 0;
     while (++byteCount) {
@@ -211,16 +204,13 @@ var getShortU16Decoder = (options = {}) => ({
       }
     }
     return [value, offset + byteCount];
-  },
-  description: options.description ?? "shortU16",
-  fixedSize: null,
-  maxSize: 3
+  }
 });
-var getShortU16Codec = (options = {}) => codecsCore.combineCodec(getShortU16Encoder(options), getShortU16Decoder(options));
-var getU128Encoder = (options = {}) => numberEncoderFactory({
+var getShortU16Codec = () => codecsCore.combineCodec(getShortU16Encoder(), getShortU16Decoder());
+var getU128Encoder = (config = {}) => numberEncoderFactory({
+  config,
   name: "u128",
-  options,
-  range: [0, BigInt("0xffffffffffffffffffffffffffffffff")],
+  range: [0n, BigInt("0xffffffffffffffffffffffffffffffff")],
   set: (view, value, le) => {
     const leftOffset = le ? 8 : 0;
     const rightOffset = le ? 0 : 8;
@@ -230,7 +220,8 @@ var getU128Encoder = (options = {}) => numberEncoderFactory({
   },
   size: 16
 });
-var getU128Decoder = (options = {}) => numberDecoderFactory({
+var getU128Decoder = (config = {}) => numberDecoderFactory({
+  config,
   get: (view, le) => {
     const leftOffset = le ? 8 : 0;
     const rightOffset = le ? 0 : 8;
@@ -239,66 +230,63 @@ var getU128Decoder = (options = {}) => numberDecoderFactory({
     return (left << 64n) + right;
   },
   name: "u128",
-  options,
   size: 16
 });
-var getU128Codec = (options = {}) => codecsCore.combineCodec(getU128Encoder(options), getU128Decoder(options));
-var getU16Encoder = (options = {}) => numberEncoderFactory({
+var getU128Codec = (config = {}) => codecsCore.combineCodec(getU128Encoder(config), getU128Decoder(config));
+var getU16Encoder = (config = {}) => numberEncoderFactory({
+  config,
   name: "u16",
-  options,
   range: [0, Number("0xffff")],
   set: (view, value, le) => view.setUint16(0, value, le),
   size: 2
 });
-var getU16Decoder = (options = {}) => numberDecoderFactory({
+var getU16Decoder = (config = {}) => numberDecoderFactory({
+  config,
   get: (view, le) => view.getUint16(0, le),
   name: "u16",
-  options,
   size: 2
 });
-var getU16Codec = (options = {}) => codecsCore.combineCodec(getU16Encoder(options), getU16Decoder(options));
-var getU32Encoder = (options = {}) => numberEncoderFactory({
+var getU16Codec = (config = {}) => codecsCore.combineCodec(getU16Encoder(config), getU16Decoder(config));
+var getU32Encoder = (config = {}) => numberEncoderFactory({
+  config,
   name: "u32",
-  options,
   range: [0, Number("0xffffffff")],
   set: (view, value, le) => view.setUint32(0, value, le),
   size: 4
 });
-var getU32Decoder = (options = {}) => numberDecoderFactory({
+var getU32Decoder = (config = {}) => numberDecoderFactory({
+  config,
   get: (view, le) => view.getUint32(0, le),
   name: "u32",
-  options,
   size: 4
 });
-var getU32Codec = (options = {}) => codecsCore.combineCodec(getU32Encoder(options), getU32Decoder(options));
-var getU64Encoder = (options = {}) => numberEncoderFactory({
+var getU32Codec = (config = {}) => codecsCore.combineCodec(getU32Encoder(config), getU32Decoder(config));
+var getU64Encoder = (config = {}) => numberEncoderFactory({
+  config,
   name: "u64",
-  options,
-  range: [0, BigInt("0xffffffffffffffff")],
+  range: [0n, BigInt("0xffffffffffffffff")],
   set: (view, value, le) => view.setBigUint64(0, BigInt(value), le),
   size: 8
 });
-var getU64Decoder = (options = {}) => numberDecoderFactory({
+var getU64Decoder = (config = {}) => numberDecoderFactory({
+  config,
   get: (view, le) => view.getBigUint64(0, le),
   name: "u64",
-  options,
   size: 8
 });
-var getU64Codec = (options = {}) => codecsCore.combineCodec(getU64Encoder(options), getU64Decoder(options));
-var getU8Encoder = (options = {}) => numberEncoderFactory({
+var getU64Codec = (config = {}) => codecsCore.combineCodec(getU64Encoder(config), getU64Decoder(config));
+var getU8Encoder = () => numberEncoderFactory({
   name: "u8",
-  options,
   range: [0, Number("0xff")],
   set: (view, value) => view.setUint8(0, value),
   size: 1
 });
-var getU8Decoder = (options = {}) => numberDecoderFactory({
+var getU8Decoder = () => numberDecoderFactory({
   get: (view) => view.getUint8(0),
   name: "u8",
-  options,
   size: 1
 });
-var getU8Codec = (options = {}) => codecsCore.combineCodec(getU8Encoder(options), getU8Decoder(options));
+var getU8Codec = () => codecsCore.combineCodec(getU8Encoder(), getU8Decoder());
 
 exports.Endian = Endian;
 exports.assertNumberIsBetweenForCodec = assertNumberIsBetweenForCodec;
@@ -341,3 +329,5 @@ exports.getU64Encoder = getU64Encoder;
 exports.getU8Codec = getU8Codec;
 exports.getU8Decoder = getU8Decoder;
 exports.getU8Encoder = getU8Encoder;
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.browser.cjs.map