@haneullabs/bcs 0.1.0

package/src/reader.ts

@@ -0,0 +1,156 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { ulebDecode } from './uleb.js';
+
+/**
+ * Class used for reading BCS data chunk by chunk. Meant to be used
+ * by some wrapper, which will make sure that data is valid and is
+ * matching the desired format.
+ *
+ * @example
+ * // data for this example is:
+ * // { a: u8, b: u32, c: bool, d: u64 }
+ *
+ * let reader = new BcsReader("647f1a060001ffffe7890423c78a050102030405");
+ * let field1 = reader.read8();
+ * let field2 = reader.read32();
+ * let field3 = reader.read8() === '1'; // bool
+ * let field4 = reader.read64();
+ * // ....
+ *
+ * Reading vectors is another deal in bcs. To read a vector, you first need to read
+ * its length using {@link readULEB}. Here's an example:
+ * @example
+ * // data encoded: { field: [1, 2, 3, 4, 5] }
+ * let reader = new BcsReader("050102030405");
+ * let vec_length = reader.readULEB();
+ * let elements = [];
+ * for (let i = 0; i < vec_length; i++) {
+ *   elements.push(reader.read8());
+ * }
+ * console.log(elements); // [1,2,3,4,5]
+ *
+ * @param {String} data HEX-encoded data (serialized BCS)
+ */
+export class BcsReader {
+	private dataView: DataView;
+	private bytePosition: number = 0;
+
+	/**
+	 * @param {Uint8Array} data Data to use as a buffer.
+	 */
+	constructor(data: Uint8Array) {
+		this.dataView = new DataView(data.buffer, data.byteOffset, data.byteLength);
+	}
+	/**
+	 * Shift current cursor position by `bytes`.
+	 *
+	 * @param {Number} bytes Number of bytes to
+	 * @returns {this} Self for possible chaining.
+	 */
+	shift(bytes: number) {
+		this.bytePosition += bytes;
+		return this;
+	}
+	/**
+	 * Read U8 value from the buffer and shift cursor by 1.
+	 * @returns
+	 */
+	read8(): number {
+		const value = this.dataView.getUint8(this.bytePosition);
+		this.shift(1);
+		return value;
+	}
+	/**
+	 * Read U16 value from the buffer and shift cursor by 2.
+	 * @returns
+	 */
+	read16(): number {
+		const value = this.dataView.getUint16(this.bytePosition, true);
+		this.shift(2);
+		return value;
+	}
+	/**
+	 * Read U32 value from the buffer and shift cursor by 4.
+	 * @returns
+	 */
+	read32(): number {
+		const value = this.dataView.getUint32(this.bytePosition, true);
+		this.shift(4);
+		return value;
+	}
+	/**
+	 * Read U64 value from the buffer and shift cursor by 8.
+	 * @returns
+	 */
+	read64(): string {
+		const value1 = this.read32();
+		const value2 = this.read32();
+
+		const result = value2.toString(16) + value1.toString(16).padStart(8, '0');
+
+		return BigInt('0x' + result).toString(10);
+	}
+	/**
+	 * Read U128 value from the buffer and shift cursor by 16.
+	 */
+	read128(): string {
+		const value1 = BigInt(this.read64());
+		const value2 = BigInt(this.read64());
+		const result = value2.toString(16) + value1.toString(16).padStart(16, '0');
+
+		return BigInt('0x' + result).toString(10);
+	}
+	/**
+	 * Read U128 value from the buffer and shift cursor by 32.
+	 * @returns
+	 */
+	read256(): string {
+		const value1 = BigInt(this.read128());
+		const value2 = BigInt(this.read128());
+		const result = value2.toString(16) + value1.toString(16).padStart(32, '0');
+
+		return BigInt('0x' + result).toString(10);
+	}
+	/**
+	 * Read `num` number of bytes from the buffer and shift cursor by `num`.
+	 * @param num Number of bytes to read.
+	 */
+	readBytes(num: number): Uint8Array {
+		const start = this.bytePosition + this.dataView.byteOffset;
+		const value = new Uint8Array(this.dataView.buffer, start, num);
+
+		this.shift(num);
+
+		return value;
+	}
+	/**
+	 * Read ULEB value - an integer of varying size. Used for enum indexes and
+	 * vector lengths.
+	 * @returns {Number} The ULEB value.
+	 */
+	readULEB(): number {
+		const start = this.bytePosition + this.dataView.byteOffset;
+		const buffer = new Uint8Array(this.dataView.buffer, start);
+		const { value, length } = ulebDecode(buffer);
+
+		this.shift(length);
+
+		return value;
+	}
+	/**
+	 * Read a BCS vector: read a length and then apply function `cb` X times
+	 * where X is the length of the vector, defined as ULEB in BCS bytes.
+	 * @param cb Callback to process elements of vector.
+	 * @returns {Array<Any>} Array of the resulting values, returned by callback.
+	 */
+	readVec(cb: (reader: BcsReader, i: number, length: number) => any): any[] {
+		const length = this.readULEB();
+		const result = [];
+		for (let i = 0; i < length; i++) {
+			result.push(cb(this, i, length));
+		}
+		return result;
+	}
+}

package/src/types.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Simplify } from '@haneullabs/utils';
+import type { BcsType } from './bcs-type.js';
+
+/**
+ * Supported encodings.
+ * Used in `Reader.toString()` as well as in `decodeStr` and `encodeStr` functions.
+ */
+export type Encoding = 'base58' | 'base64' | 'hex';
+
+export type InferBcsType<T extends BcsType<any>> = T extends BcsType<infer U, any> ? U : never;
+export type InferBcsInput<T extends BcsType<any, any>> =
+	T extends BcsType<any, infer U> ? U : never;
+
+export type EnumOutputShape<
+	T extends Record<string, unknown>,
+	Keys extends string = Extract<keyof T, string>,
+	Values = T[keyof T] extends infer Type ? (Type extends BcsType<infer U> ? U : never) : never,
+> = 0 extends Values
+	? EnumOutputShapeWithKeys<T, never>
+	: 0n extends Values
+		? EnumOutputShapeWithKeys<T, never>
+		: '' extends Values
+			? EnumOutputShapeWithKeys<T, never>
+			: false extends Values
+				? EnumOutputShapeWithKeys<T, never>
+				: EnumOutputShapeWithKeys<T, Keys>;
+
+export type EnumOutputShapeWithKeys<T extends Record<string, unknown>, Keys extends string> = {
+	[K in keyof T]: Exclude<Keys, K> extends infer Empty extends string
+		? Simplify<
+				{ [K2 in K]: T[K] } & { [K in Empty]?: never } & {
+					$kind: K;
+				}
+			>
+		: never;
+}[keyof T];
+
+export type EnumInputShape<T extends Record<string, unknown>> = {
+	[K in keyof T]: { [K2 in K]: T[K] };
+}[keyof T];
+
+export type JoinString<T, Sep extends string> = T extends readonly [
+	infer F extends string,
+	...infer R extends string[],
+]
+	? [] extends R
+		? F
+		: `${F}${Sep}${JoinString<R, Sep>}`
+	: '';

package/src/uleb.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Helper utility: write number as an ULEB array.
+// Original code is taken from: https://www.npmjs.com/package/uleb128 (no longer exists)
+export function ulebEncode(num: number | bigint): number[] {
+	let bigNum = BigInt(num);
+	const arr: number[] = [];
+	let len = 0;
+
+	if (bigNum === 0n) {
+		return [0];
+	}
+
+	while (bigNum > 0) {
+		arr[len] = Number(bigNum & 0x7fn);
+		bigNum >>= 7n;
+		if (bigNum > 0n) {
+			arr[len] |= 0x80;
+		}
+		len += 1;
+	}
+
+	return arr;
+}
+
+// Helper utility: decode ULEB as an array of numbers.
+// Original code is taken from: https://www.npmjs.com/package/uleb128 (no longer exists)
+export function ulebDecode(arr: number[] | Uint8Array): {
+	value: number;
+	length: number;
+} {
+	let total = 0n;
+	let shift = 0n;
+	let len = 0;
+
+	// eslint-disable-next-line no-constant-condition
+	while (true) {
+		if (len >= arr.length) {
+			throw new Error('ULEB decode error: buffer overflow');
+		}
+
+		const byte = arr[len];
+		len += 1;
+		total += BigInt(byte & 0x7f) << shift;
+		if ((byte & 0x80) === 0) {
+			break;
+		}
+		shift += 7n;
+	}
+
+	// TODO: return bigint in next major version
+	if (total > BigInt(Number.MAX_SAFE_INTEGER)) {
+		throw new Error('ULEB decode error: value exceeds MAX_SAFE_INTEGER');
+	}
+
+	return {
+		value: Number(total),
+		length: len,
+	};
+}

package/src/utils.ts

@@ -0,0 +1,75 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { fromBase58, fromBase64, fromHex, toBase58, toBase64, toHex } from '@haneullabs/utils';
+import type { Encoding } from './types.js';
+
+/**
+ * Encode data with either `hex` or `base64`.
+ *
+ * @param {Uint8Array} data Data to encode.
+ * @param {String} encoding Encoding to use: base64 or hex
+ * @returns {String} Encoded value.
+ */
+export function encodeStr(data: Uint8Array, encoding: Encoding): string {
+	switch (encoding) {
+		case 'base58':
+			return toBase58(data);
+		case 'base64':
+			return toBase64(data);
+		case 'hex':
+			return toHex(data);
+		default:
+			throw new Error('Unsupported encoding, supported values are: base64, hex');
+	}
+}
+
+/**
+ * Decode either `base64` or `hex` data.
+ *
+ * @param {String} data Data to encode.
+ * @param {String} encoding Encoding to use: base64 or hex
+ * @returns {Uint8Array} Encoded value.
+ */
+export function decodeStr(data: string, encoding: Encoding): Uint8Array {
+	switch (encoding) {
+		case 'base58':
+			return fromBase58(data);
+		case 'base64':
+			return fromBase64(data);
+		case 'hex':
+			return fromHex(data);
+		default:
+			throw new Error('Unsupported encoding, supported values are: base64, hex');
+	}
+}
+
+export function splitGenericParameters(
+	str: string,
+	genericSeparators: [string, string] = ['<', '>'],
+) {
+	const [left, right] = genericSeparators;
+	const tok = [];
+	let word = '';
+	let nestedAngleBrackets = 0;
+
+	for (let i = 0; i < str.length; i++) {
+		const char = str[i];
+		if (char === left) {
+			nestedAngleBrackets++;
+		}
+		if (char === right) {
+			nestedAngleBrackets--;
+		}
+		if (nestedAngleBrackets === 0 && char === ',') {
+			tok.push(word.trim());
+			word = '';
+			continue;
+		}
+		word += char;
+	}
+
+	tok.push(word.trim());
+
+	return tok;
+}

package/src/writer.ts

@@ -0,0 +1,222 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Encoding } from './types.js';
+import { ulebEncode } from './uleb.js';
+import { encodeStr } from './utils.js';
+
+export interface BcsWriterOptions {
+	/** The initial size (in bytes) of the buffer tht will be allocated */
+	initialSize?: number;
+	/** The maximum size (in bytes) that the buffer is allowed to grow to */
+	maxSize?: number;
+	/** The amount of bytes that will be allocated whenever additional memory is required */
+	allocateSize?: number;
+}
+
+/**
+ * Class used to write BCS data into a buffer. Initializer requires
+ * some size of a buffer to init; default value for this buffer is 1KB.
+ *
+ * Most methods are chainable, so it is possible to write them in one go.
+ *
+ * @example
+ * let serialized = new BcsWriter()
+ *   .write8(10)
+ *   .write32(1000000)
+ *   .write64(10000001000000)
+ *   .hex();
+ */
+
+/**
+ * Set of methods that allows data encoding/decoding as standalone
+ * BCS value or a part of a composed structure/vector.
+ */
+export class BcsWriter {
+	private dataView: DataView<ArrayBuffer>;
+	private bytePosition: number = 0;
+	private size: number;
+	private maxSize: number;
+	private allocateSize: number;
+
+	constructor({
+		initialSize = 1024,
+		maxSize = Infinity,
+		allocateSize = 1024,
+	}: BcsWriterOptions = {}) {
+		this.size = initialSize;
+		this.maxSize = maxSize;
+		this.allocateSize = allocateSize;
+		this.dataView = new DataView(new ArrayBuffer(initialSize));
+	}
+
+	private ensureSizeOrGrow(bytes: number) {
+		const requiredSize = this.bytePosition + bytes;
+		if (requiredSize > this.size) {
+			const nextSize = Math.min(
+				this.maxSize,
+				Math.max(this.size + requiredSize, this.size + this.allocateSize),
+			);
+			if (requiredSize > nextSize) {
+				throw new Error(
+					`Attempting to serialize to BCS, but buffer does not have enough size. Allocated size: ${this.size}, Max size: ${this.maxSize}, Required size: ${requiredSize}`,
+				);
+			}
+
+			this.size = nextSize;
+			const nextBuffer = new ArrayBuffer(this.size);
+			new Uint8Array(nextBuffer).set(new Uint8Array(this.dataView.buffer));
+			this.dataView = new DataView(nextBuffer);
+		}
+	}
+
+	/**
+	 * Shift current cursor position by `bytes`.
+	 *
+	 * @param {Number} bytes Number of bytes to
+	 * @returns {this} Self for possible chaining.
+	 */
+	shift(bytes: number): this {
+		this.bytePosition += bytes;
+		return this;
+	}
+	/**
+	 * Write a U8 value into a buffer and shift cursor position by 1.
+	 * @param {Number} value Value to write.
+	 * @returns {this}
+	 */
+	write8(value: number | bigint): this {
+		this.ensureSizeOrGrow(1);
+		this.dataView.setUint8(this.bytePosition, Number(value));
+		return this.shift(1);
+	}
+
+	/**
+	 * Write a U8 value into a buffer and shift cursor position by 1.
+	 * @param {Number} value Value to write.
+	 * @returns {this}
+	 */
+	writeBytes(bytes: Uint8Array): this {
+		this.ensureSizeOrGrow(bytes.length);
+
+		for (let i = 0; i < bytes.length; i++) {
+			this.dataView.setUint8(this.bytePosition + i, bytes[i]);
+		}
+
+		return this.shift(bytes.length);
+	}
+	/**
+	 * Write a U16 value into a buffer and shift cursor position by 2.
+	 * @param {Number} value Value to write.
+	 * @returns {this}
+	 */
+	write16(value: number | bigint): this {
+		this.ensureSizeOrGrow(2);
+		this.dataView.setUint16(this.bytePosition, Number(value), true);
+		return this.shift(2);
+	}
+	/**
+	 * Write a U32 value into a buffer and shift cursor position by 4.
+	 * @param {Number} value Value to write.
+	 * @returns {this}
+	 */
+	write32(value: number | bigint): this {
+		this.ensureSizeOrGrow(4);
+		this.dataView.setUint32(this.bytePosition, Number(value), true);
+		return this.shift(4);
+	}
+	/**
+	 * Write a U64 value into a buffer and shift cursor position by 8.
+	 * @param {bigint} value Value to write.
+	 * @returns {this}
+	 */
+	write64(value: number | bigint): this {
+		toLittleEndian(BigInt(value), 8).forEach((el) => this.write8(el));
+
+		return this;
+	}
+	/**
+	 * Write a U128 value into a buffer and shift cursor position by 16.
+	 *
+	 * @param {bigint} value Value to write.
+	 * @returns {this}
+	 */
+	write128(value: number | bigint): this {
+		toLittleEndian(BigInt(value), 16).forEach((el) => this.write8(el));
+
+		return this;
+	}
+	/**
+	 * Write a U256 value into a buffer and shift cursor position by 16.
+	 *
+	 * @param {bigint} value Value to write.
+	 * @returns {this}
+	 */
+	write256(value: number | bigint): this {
+		toLittleEndian(BigInt(value), 32).forEach((el) => this.write8(el));
+
+		return this;
+	}
+	/**
+	 * Write a ULEB value into a buffer and shift cursor position by number of bytes
+	 * written.
+	 * @param {Number} value Value to write.
+	 * @returns {this}
+	 */
+	writeULEB(value: number): this {
+		ulebEncode(value).forEach((el) => this.write8(el));
+		return this;
+	}
+	/**
+	 * Write a vector into a buffer by first writing the vector length and then calling
+	 * a callback on each passed value.
+	 *
+	 * @param {Array<Any>} vector Array of elements to write.
+	 * @param {WriteVecCb} cb Callback to call on each element of the vector.
+	 * @returns {this}
+	 */
+	writeVec(vector: any[], cb: (writer: BcsWriter, el: any, i: number, len: number) => void): this {
+		this.writeULEB(vector.length);
+		Array.from(vector).forEach((el, i) => cb(this, el, i, vector.length));
+		return this;
+	}
+
+	/**
+	 * Adds support for iterations over the object.
+	 * @returns {Uint8Array}
+	 */
+	// oxlint-disable-next-line require-yields
+	*[Symbol.iterator](): Iterator<number, Iterable<number>> {
+		for (let i = 0; i < this.bytePosition; i++) {
+			yield this.dataView.getUint8(i);
+		}
+		return this.toBytes();
+	}
+
+	/**
+	 * Get underlying buffer taking only value bytes (in case initial buffer size was bigger).
+	 * @returns {Uint8Array} Resulting bcs.
+	 */
+	toBytes(): Uint8Array<ArrayBuffer> {
+		return new Uint8Array(this.dataView.buffer.slice(0, this.bytePosition));
+	}
+
+	/**
+	 * Represent data as 'hex' or 'base64'
+	 * @param encoding Encoding to use: 'base64' or 'hex'
+	 */
+	toString(encoding: Encoding): string {
+		return encodeStr(this.toBytes(), encoding);
+	}
+}
+
+function toLittleEndian(bigint: bigint, size: number) {
+	const result = new Uint8Array(size);
+	let i = 0;
+	while (bigint > 0) {
+		result[i] = Number(bigint % BigInt(256));
+		bigint = bigint / BigInt(256);
+		i += 1;
+	}
+	return result;
+}