algosdk 2.9.0 → 3.0.0-beta.1

package/src/encoding/schema/array.ts

@@ -0,0 +1,66 @@
+import {
+  Schema,
+  MsgpackEncodingData,
+  MsgpackRawStringProvider,
+  JSONEncodingData,
+  PrepareJSONOptions,
+} from '../encoding.js';
+
+/* eslint-disable class-methods-use-this */
+
+export class ArraySchema extends Schema {
+  constructor(public readonly itemSchema: Schema) {
+    super();
+  }
+
+  public defaultValue(): unknown[] {
+    return [];
+  }
+
+  public isDefaultValue(data: unknown): boolean {
+    return Array.isArray(data) && data.length === 0;
+  }
+
+  public prepareMsgpack(data: unknown): MsgpackEncodingData {
+    if (Array.isArray(data)) {
+      return data.map((item) => this.itemSchema.prepareMsgpack(item));
+    }
+    throw new Error('ArraySchema data must be an array');
+  }
+
+  public fromPreparedMsgpack(
+    encoded: MsgpackEncodingData,
+    rawStringProvider: MsgpackRawStringProvider
+  ): unknown[] {
+    if (Array.isArray(encoded)) {
+      return encoded.map((item, index) =>
+        this.itemSchema.fromPreparedMsgpack(
+          item,
+          rawStringProvider.withArrayElement(index)
+        )
+      );
+    }
+    throw new Error(
+      `ArraySchema encoded data must be an array: ${encoded} (${typeof encoded})`
+    );
+  }
+
+  public prepareJSON(
+    data: unknown,
+    options: PrepareJSONOptions
+  ): JSONEncodingData {
+    if (Array.isArray(data)) {
+      return data.map((item) => this.itemSchema.prepareJSON(item, options));
+    }
+    throw new Error('ArraySchema data must be an array');
+  }
+
+  public fromPreparedJSON(encoded: JSONEncodingData): unknown[] {
+    if (Array.isArray(encoded)) {
+      return encoded.map((item) => this.itemSchema.fromPreparedJSON(item));
+    }
+    throw new Error(
+      `ArraySchema encoded data must be an array: ${encoded} (${typeof encoded})`
+    );
+  }
+}

package/src/encoding/schema/binarystring.ts

@@ -0,0 +1,73 @@
+import { RawBinaryString } from 'algorand-msgpack';
+import {
+  Schema,
+  MsgpackEncodingData,
+  MsgpackRawStringProvider,
+  JSONEncodingData,
+  PrepareJSONOptions,
+} from '../encoding.js';
+import { coerceToBytes, bytesToString, bytesToBase64 } from '../binarydata.js';
+import { arrayEqual } from '../../utils/utils.js';
+
+/* eslint-disable class-methods-use-this */
+
+/**
+ * SpecialCaseBinaryStringSchema is a schema for byte arrays which are encoded
+ * as strings in msgpack and JSON.
+ *
+ * This schema allows lossless conversion between the in memory representation
+ * and the msgpack encoded representation, but NOT between the in memory and
+ * JSON encoded representations if the byte array contains invalid UTF-8
+ * sequences.
+ */
+export class SpecialCaseBinaryStringSchema extends Schema {
+  public defaultValue(): Uint8Array {
+    return new Uint8Array();
+  }
+
+  public isDefaultValue(data: unknown): boolean {
+    return data instanceof Uint8Array && data.byteLength === 0;
+  }
+
+  public prepareMsgpack(data: unknown): MsgpackEncodingData {
+    if (data instanceof Uint8Array) {
+      // Cast is needed because RawBinaryString is not part of the standard MsgpackEncodingData
+      return new RawBinaryString(data) as unknown as MsgpackEncodingData;
+    }
+    throw new Error(`Invalid byte array: (${typeof data}) ${data}`);
+  }
+
+  public fromPreparedMsgpack(
+    _encoded: MsgpackEncodingData,
+    rawStringProvider: MsgpackRawStringProvider
+  ): Uint8Array {
+    return rawStringProvider.getRawStringAtCurrentLocation();
+  }
+
+  public prepareJSON(
+    data: unknown,
+    options: PrepareJSONOptions
+  ): JSONEncodingData {
+    if (data instanceof Uint8Array) {
+      // Not safe to convert to string for all binary data
+      const stringValue = bytesToString(data);
+      if (
+        !options.lossyBinaryStringConversion &&
+        !arrayEqual(coerceToBytes(stringValue), data)
+      ) {
+        throw new Error(
+          `Invalid UTF-8 byte array encountered. Encode with lossyBinaryStringConversion enabled to bypass this check. Base64 value: ${bytesToBase64(data)}`
+        );
+      }
+      return stringValue;
+    }
+    throw new Error(`Invalid byte array: (${typeof data}) ${data}`);
+  }
+
+  public fromPreparedJSON(encoded: JSONEncodingData): Uint8Array {
+    if (typeof encoded === 'string') {
+      return coerceToBytes(encoded);
+    }
+    throw new Error(`Invalid byte array: (${typeof encoded}) ${encoded}`);
+  }
+}

package/src/encoding/schema/blockhash.ts

@@ -0,0 +1,84 @@
+import base32 from 'hi-base32';
+import {
+  Schema,
+  MsgpackEncodingData,
+  MsgpackRawStringProvider,
+  JSONEncodingData,
+  PrepareJSONOptions,
+} from '../encoding.js';
+
+/**
+ * Length of a block hash in bytes
+ */
+const blockHashByteLength = 32;
+
+/* eslint-disable class-methods-use-this */
+
+/**
+ * Length of a 32-byte encoded in base32 without padding
+ */
+const base32Length = 52;
+
+/**
+ * BlockHashSchema is a schema for block hashes.
+ *
+ * In msgapck, these types are encoded as 32-byte binary strings. In JSON, they
+ * are encoded as strings prefixed with "blk-" followed by the base32 encoding
+ * of the 32-byte block hash without any padding.
+ */
+export class BlockHashSchema extends Schema {
+  public defaultValue(): Uint8Array {
+    return new Uint8Array(blockHashByteLength);
+  }
+
+  public isDefaultValue(data: unknown): boolean {
+    return (
+      data instanceof Uint8Array &&
+      data.byteLength === blockHashByteLength &&
+      data.every((byte) => byte === 0)
+    );
+  }
+
+  public prepareMsgpack(data: unknown): MsgpackEncodingData {
+    if (data instanceof Uint8Array && data.byteLength === blockHashByteLength) {
+      return data;
+    }
+    throw new Error(`Invalid block hash: (${typeof data}) ${data}`);
+  }
+
+  public fromPreparedMsgpack(
+    encoded: MsgpackEncodingData,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _rawStringProvider: MsgpackRawStringProvider
+  ): Uint8Array {
+    if (
+      encoded instanceof Uint8Array &&
+      encoded.byteLength === blockHashByteLength
+    ) {
+      return encoded;
+    }
+    throw new Error(`Invalid block hash: (${typeof encoded}) ${encoded}`);
+  }
+
+  public prepareJSON(
+    data: unknown,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _options: PrepareJSONOptions
+  ): JSONEncodingData {
+    if (data instanceof Uint8Array && data.byteLength === blockHashByteLength) {
+      return `blk-${base32.encode(data).slice(0, base32Length)}`;
+    }
+    throw new Error(`Invalid block hash: (${typeof data}) ${data}`);
+  }
+
+  public fromPreparedJSON(encoded: JSONEncodingData): Uint8Array {
+    if (
+      typeof encoded === 'string' &&
+      encoded.length === base32Length + 4 &&
+      encoded.startsWith('blk-')
+    ) {
+      return Uint8Array.from(base32.decode.asBytes(encoded.slice(4)));
+    }
+    throw new Error(`Invalid block hash: (${typeof encoded}) ${encoded}`);
+  }
+}

package/src/encoding/schema/boolean.ts

@@ -0,0 +1,54 @@
+import {
+  Schema,
+  MsgpackEncodingData,
+  MsgpackRawStringProvider,
+  JSONEncodingData,
+  PrepareJSONOptions,
+} from '../encoding.js';
+
+/* eslint-disable class-methods-use-this */
+
+export class BooleanSchema extends Schema {
+  public defaultValue(): boolean {
+    return false;
+  }
+
+  public isDefaultValue(data: unknown): boolean {
+    return data === false;
+  }
+
+  public prepareMsgpack(data: unknown): MsgpackEncodingData {
+    if (typeof data === 'boolean') {
+      return data;
+    }
+    throw new Error('Invalid boolean');
+  }
+
+  public fromPreparedMsgpack(
+    encoded: MsgpackEncodingData,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _rawStringProvider: MsgpackRawStringProvider
+  ): boolean {
+    if (typeof encoded === 'boolean') {
+      return encoded;
+    }
+    throw new Error('Invalid boolean');
+  }
+
+  public prepareJSON(
+    data: unknown, // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _options: PrepareJSONOptions
+  ): JSONEncodingData {
+    if (typeof data === 'boolean') {
+      return data;
+    }
+    throw new Error('Invalid boolean');
+  }
+
+  public fromPreparedJSON(encoded: JSONEncodingData): boolean {
+    if (typeof encoded === 'boolean') {
+      return encoded;
+    }
+    throw new Error('Invalid boolean');
+  }
+}

package/src/encoding/schema/bytearray.ts

@@ -0,0 +1,127 @@
+import {
+  Schema,
+  MsgpackEncodingData,
+  MsgpackRawStringProvider,
+  JSONEncodingData,
+  PrepareJSONOptions,
+} from '../encoding.js';
+import { base64ToBytes, bytesToBase64 } from '../binarydata.js';
+
+/* eslint-disable class-methods-use-this */
+
+export class ByteArraySchema extends Schema {
+  public defaultValue(): Uint8Array {
+    return new Uint8Array();
+  }
+
+  public isDefaultValue(data: unknown): boolean {
+    return data instanceof Uint8Array && data.byteLength === 0;
+  }
+
+  public prepareMsgpack(data: unknown): MsgpackEncodingData {
+    if (data instanceof Uint8Array) {
+      return data;
+    }
+    throw new Error(`Invalid byte array: (${typeof data}) ${data}`);
+  }
+
+  public fromPreparedMsgpack(
+    encoded: MsgpackEncodingData,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _rawStringProvider: MsgpackRawStringProvider
+  ): Uint8Array {
+    if (encoded instanceof Uint8Array) {
+      return encoded;
+    }
+    throw new Error(`Invalid byte array: (${typeof encoded}) ${encoded}`);
+  }
+
+  public prepareJSON(
+    data: unknown,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _options: PrepareJSONOptions
+  ): JSONEncodingData {
+    if (data instanceof Uint8Array) {
+      return bytesToBase64(data);
+    }
+    throw new Error(`Invalid byte array: (${typeof data}) ${data}`);
+  }
+
+  public fromPreparedJSON(encoded: JSONEncodingData): Uint8Array {
+    if (typeof encoded === 'string') {
+      return base64ToBytes(encoded);
+    }
+    throw new Error(`Invalid byte array: (${typeof encoded}) ${encoded}`);
+  }
+}
+
+export class FixedLengthByteArraySchema extends Schema {
+  constructor(public readonly length: number) {
+    super();
+  }
+
+  public defaultValue(): Uint8Array {
+    return new Uint8Array(this.length);
+  }
+
+  public isDefaultValue(data: unknown): boolean {
+    return (
+      data instanceof Uint8Array &&
+      data.byteLength === this.length &&
+      data.every((byte) => byte === 0)
+    );
+  }
+
+  public prepareMsgpack(data: unknown): MsgpackEncodingData {
+    if (data instanceof Uint8Array) {
+      if (data.byteLength === this.length) {
+        return data;
+      }
+      throw new Error(
+        `Invalid byte array length: wanted ${this.length}, got ${data.byteLength}`
+      );
+    }
+    throw new Error('Invalid byte array');
+  }
+
+  public fromPreparedMsgpack(
+    encoded: MsgpackEncodingData,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _rawStringProvider: MsgpackRawStringProvider
+  ): Uint8Array {
+    if (encoded instanceof Uint8Array) {
+      if (encoded.byteLength === this.length) {
+        return encoded;
+      }
+      throw new Error(
+        `Invalid byte array length: wanted ${this.length}, got ${encoded.byteLength}`
+      );
+    }
+    throw new Error('Invalid byte array');
+  }
+
+  public prepareJSON(data: unknown): JSONEncodingData {
+    if (data instanceof Uint8Array) {
+      if (data.byteLength === this.length) {
+        return bytesToBase64(data);
+      }
+      throw new Error(
+        `Invalid byte array length: wanted ${this.length}, got ${data.byteLength}`
+      );
+    }
+    throw new Error('Invalid byte array');
+  }
+
+  public fromPreparedJSON(encoded: JSONEncodingData): Uint8Array {
+    if (typeof encoded === 'string') {
+      const bytes = base64ToBytes(encoded);
+      if (bytes.byteLength === this.length) {
+        return bytes;
+      }
+      throw new Error(
+        `Invalid byte array length: wanted ${this.length}, got ${bytes.byteLength}`
+      );
+    }
+    throw new Error('Invalid base64 byte array');
+  }
+}

package/src/encoding/schema/index.ts

@@ -0,0 +1,26 @@
+export { BooleanSchema } from './boolean.js';
+export { StringSchema } from './string.js';
+export { Uint64Schema } from './uint64.js';
+
+export { AddressSchema } from './address.js';
+export { ByteArraySchema, FixedLengthByteArraySchema } from './bytearray.js';
+
+export { BlockHashSchema } from './blockhash.js';
+
+export { SpecialCaseBinaryStringSchema } from './binarystring.js';
+
+export { ArraySchema } from './array.js';
+export {
+  NamedMapSchema,
+  NamedMapEntry,
+  allOmitEmpty,
+  combineMaps,
+  convertMap,
+  Uint64MapSchema,
+  StringMapSchema,
+  ByteArrayMapSchema,
+  SpecialCaseBinaryStringMapSchema,
+} from './map.js';
+export { OptionalSchema } from './optional.js';
+
+export { UntypedSchema } from './untyped.js';