@haneullabs/bcs 0.1.0

package/src/bcs.ts

@@ -0,0 +1,543 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { BcsTypeOptions } from './bcs-type.js';
+import {
+	BcsEnum,
+	BcsStruct,
+	BcsTuple,
+	BcsType,
+	bigUIntBcsType,
+	dynamicSizeBcsType,
+	fixedSizeBcsType,
+	lazyBcsType,
+	stringLikeBcsType,
+	uIntBcsType,
+} from './bcs-type.js';
+import type {
+	EnumInputShape,
+	EnumOutputShape,
+	InferBcsInput,
+	InferBcsType,
+	JoinString,
+} from './types.js';
+import { ulebEncode } from './uleb.js';
+
+function fixedArray<T extends BcsType<any>, Name extends string = string>(
+	size: number,
+	type: T,
+	options?: BcsTypeOptions<
+		InferBcsType<T>[],
+		Iterable<InferBcsInput<T>> & { length: number },
+		Name
+	>,
+): BcsType<InferBcsType<T>[], Iterable<InferBcsInput<T>> & { length: number }, Name>;
+function fixedArray<T, Input, Name extends string = string>(
+	size: number,
+	type: BcsType<T, Input>,
+	options?: BcsTypeOptions<T[], Iterable<Input> & { length: number }, Name>,
+): BcsType<T[], Iterable<Input> & { length: number }, Name>;
+function fixedArray<T extends BcsType<any>, Name extends string = `${T['name']}[${number}]`>(
+	size: number,
+	type: T,
+	options?: BcsTypeOptions<
+		InferBcsType<T>[],
+		Iterable<InferBcsInput<T>> & { length: number },
+		Name
+	>,
+): BcsType<InferBcsType<T>[], Iterable<InferBcsInput<T>> & { length: number }, Name> {
+	return new BcsType<InferBcsType<T>[], Iterable<InferBcsInput<T>> & { length: number }, Name>({
+		read: (reader) => {
+			const result: InferBcsType<T>[] = new Array(size);
+			for (let i = 0; i < size; i++) {
+				result[i] = type.read(reader);
+			}
+			return result;
+		},
+		write: (value, writer) => {
+			for (const item of value) {
+				type.write(item, writer);
+			}
+		},
+		...options,
+		name: (options?.name ?? `${type.name}[${size}]`) as Name,
+		validate: (value) => {
+			options?.validate?.(value);
+			if (!value || typeof value !== 'object' || !('length' in value)) {
+				throw new TypeError(`Expected array, found ${typeof value}`);
+			}
+			if (value.length !== size) {
+				throw new TypeError(`Expected array of length ${size}, found ${value.length}`);
+			}
+		},
+	});
+}
+
+function option<T extends BcsType<any>>(
+	type: T,
+): BcsType<InferBcsType<T> | null, InferBcsInput<T> | null | undefined, `Option<${T['name']}>`>;
+function option<T, Input, Name extends string = string>(
+	type: BcsType<T, Input, Name>,
+): BcsType<T | null, Input | null | undefined>;
+function option<T extends BcsType<any>>(
+	type: T,
+): BcsType<InferBcsType<T> | null, InferBcsInput<T> | null | undefined, `Option<${T['name']}>`> {
+	return bcs
+		.enum(`Option<${type.name}>`, {
+			None: null,
+			Some: type,
+		})
+		.transform({
+			input: (value: InferBcsInput<T> | null | undefined) => {
+				if (value == null) {
+					return { None: true };
+				}
+
+				return { Some: value };
+			},
+			output: (value) => {
+				if (value.$kind === 'Some') {
+					return value.Some as InferBcsType<T>;
+				}
+
+				return null;
+			},
+		});
+}
+
+function vector<T extends BcsType<any>, Name extends string = `vector<${T['name']}>`>(
+	type: T,
+	options?: BcsTypeOptions<
+		InferBcsType<T>[],
+		Iterable<InferBcsInput<T>> & { length: number },
+		Name
+	>,
+): BcsType<InferBcsType<T>[], Iterable<InferBcsInput<T>> & { length: number }, Name>;
+function vector<T, Input, Name extends string = string>(
+	type: BcsType<T, Input, Name>,
+	options?: BcsTypeOptions<T[], Iterable<Input> & { length: number }, `vector<${Name}>`>,
+): BcsType<T[], Iterable<Input> & { length: number }, `vector<${Name}>`>;
+function vector<T extends BcsType<any>, Name extends string = `vector<${T['name']}>`>(
+	type: T,
+	options?: BcsTypeOptions<
+		InferBcsType<T>[],
+		Iterable<InferBcsInput<T>> & { length: number },
+		Name
+	>,
+): BcsType<InferBcsType<T>[], Iterable<InferBcsInput<T>> & { length: number }, Name> {
+	return new BcsType<InferBcsType<T>[], Iterable<InferBcsInput<T>> & { length: number }, Name>({
+		read: (reader) => {
+			const length = reader.readULEB();
+			const result: InferBcsType<T>[] = new Array(length);
+			for (let i = 0; i < length; i++) {
+				result[i] = type.read(reader);
+			}
+			return result;
+		},
+		write: (value, writer) => {
+			writer.writeULEB(value.length);
+			for (const item of value) {
+				type.write(item, writer);
+			}
+		},
+		...options,
+		name: (options?.name ?? `vector<${type.name}>`) as Name,
+		validate: (value) => {
+			options?.validate?.(value);
+			if (!value || typeof value !== 'object' || !('length' in value)) {
+				throw new TypeError(`Expected array, found ${typeof value}`);
+			}
+		},
+	});
+}
+
+function map<K extends BcsType<any>, V extends BcsType<any>>(
+	keyType: K,
+	valueType: V,
+): BcsType<
+	Map<InferBcsType<K>, InferBcsType<V>>,
+	Map<InferBcsInput<K>, InferBcsInput<V>>,
+	`Map<${K['name']}, ${V['name']}>`
+>;
+function map<K, V, InputK = K, InputV = V>(
+	keyType: BcsType<K, InputK>,
+	valueType: BcsType<V, InputV>,
+): BcsType<Map<K, V>, Map<InputK, InputV>, `Map<${string}, ${string}>`>;
+function map<K extends BcsType<any>, V extends BcsType<any>>(
+	keyType: K,
+	valueType: V,
+): BcsType<
+	Map<InferBcsType<K>, InferBcsType<V>>,
+	Map<InferBcsInput<K>, InferBcsInput<V>>,
+	`Map<${K['name']}, ${V['name']}>`
+> {
+	return bcs.vector(bcs.tuple([keyType, valueType])).transform({
+		name: `Map<${keyType.name}, ${valueType.name}>`,
+		input: (value: Map<InferBcsInput<K>, InferBcsInput<V>>) => {
+			return [...value.entries()];
+		},
+		output: (value) => {
+			const result = new Map<InferBcsType<K>, InferBcsType<V>>();
+			for (const [key, val] of value) {
+				result.set(key, val);
+			}
+			return result;
+		},
+	});
+}
+
+export const bcs = {
+	/**
+	 * Creates a BcsType that can be used to read and write an 8-bit unsigned integer.
+	 * @example
+	 * bcs.u8().serialize(255).toBytes() // Uint8Array [ 255 ]
+	 */
+	u8(options?: BcsTypeOptions<number>) {
+		return uIntBcsType({
+			readMethod: 'read8',
+			writeMethod: 'write8',
+			size: 1,
+			maxValue: 2 ** 8 - 1,
+			...options,
+			name: (options?.name ?? 'u8') as 'u8',
+		});
+	},
+
+	/**
+	 * Creates a BcsType that can be used to read and write a 16-bit unsigned integer.
+	 * @example
+	 * bcs.u16().serialize(65535).toBytes() // Uint8Array [ 255, 255 ]
+	 */
+	u16(options?: BcsTypeOptions<number>) {
+		return uIntBcsType({
+			readMethod: 'read16',
+			writeMethod: 'write16',
+			size: 2,
+			maxValue: 2 ** 16 - 1,
+			...options,
+			name: (options?.name ?? 'u16') as 'u16',
+		});
+	},
+
+	/**
+	 * Creates a BcsType that can be used to read and write a 32-bit unsigned integer.
+	 * @example
+	 * bcs.u32().serialize(4294967295).toBytes() // Uint8Array [ 255, 255, 255, 255 ]
+	 */
+	u32(options?: BcsTypeOptions<number>) {
+		return uIntBcsType({
+			readMethod: 'read32',
+			writeMethod: 'write32',
+			size: 4,
+			maxValue: 2 ** 32 - 1,
+			...options,
+			name: (options?.name ?? 'u32') as 'u32',
+		});
+	},
+
+	/**
+	 * Creates a BcsType that can be used to read and write a 64-bit unsigned integer.
+	 * @example
+	 * bcs.u64().serialize(1).toBytes() // Uint8Array [ 1, 0, 0, 0, 0, 0, 0, 0 ]
+	 */
+	u64(options?: BcsTypeOptions<string, number | bigint | string>) {
+		return bigUIntBcsType({
+			readMethod: 'read64',
+			writeMethod: 'write64',
+			size: 8,
+			maxValue: 2n ** 64n - 1n,
+			...options,
+			name: (options?.name ?? 'u64') as 'u64',
+		});
+	},
+
+	/**
+	 * Creates a BcsType that can be used to read and write a 128-bit unsigned integer.
+	 * @example
+	 * bcs.u128().serialize(1).toBytes() // Uint8Array [ 1, ..., 0 ]
+	 */
+	u128(options?: BcsTypeOptions<string, number | bigint | string>) {
+		return bigUIntBcsType({
+			readMethod: 'read128',
+			writeMethod: 'write128',
+			size: 16,
+			maxValue: 2n ** 128n - 1n,
+			...options,
+			name: (options?.name ?? 'u128') as 'u128',
+		});
+	},
+
+	/**
+	 * Creates a BcsType that can be used to read and write a 256-bit unsigned integer.
+	 * @example
+	 * bcs.u256().serialize(1).toBytes() // Uint8Array [ 1, ..., 0 ]
+	 */
+	u256(options?: BcsTypeOptions<string, number | bigint | string>) {
+		return bigUIntBcsType({
+			readMethod: 'read256',
+			writeMethod: 'write256',
+			size: 32,
+			maxValue: 2n ** 256n - 1n,
+			...options,
+			name: (options?.name ?? 'u256') as 'u256',
+		});
+	},
+
+	/**
+	 * Creates a BcsType that can be used to read and write boolean values.
+	 * @example
+	 * bcs.bool().serialize(true).toBytes() // Uint8Array [ 1 ]
+	 */
+	bool(options?: BcsTypeOptions<boolean>) {
+		return fixedSizeBcsType({
+			size: 1,
+			read: (reader) => reader.read8() === 1,
+			write: (value, writer) => writer.write8(value ? 1 : 0),
+			...options,
+			name: (options?.name ?? 'bool') as 'bool',
+			validate: (value) => {
+				options?.validate?.(value);
+				if (typeof value !== 'boolean') {
+					throw new TypeError(`Expected boolean, found ${typeof value}`);
+				}
+			},
+		});
+	},
+
+	/**
+	 * Creates a BcsType that can be used to read and write unsigned LEB encoded integers
+	 * @example
+	 *
+	 */
+	uleb128(options?: BcsTypeOptions<number>) {
+		return dynamicSizeBcsType({
+			read: (reader) => reader.readULEB(),
+			serialize: (value) => {
+				return Uint8Array.from(ulebEncode(value));
+			},
+			...options,
+			name: (options?.name ?? 'uleb128') as 'uleb128',
+		});
+	},
+
+	/**
+	 * Creates a BcsType representing a fixed length byte array
+	 * @param size The number of bytes this types represents
+	 * @example
+	 * bcs.bytes(3).serialize(new Uint8Array([1, 2, 3])).toBytes() // Uint8Array [1, 2, 3]
+	 */
+	bytes<T extends number>(size: T, options?: BcsTypeOptions<Uint8Array, Iterable<number>>) {
+		return fixedSizeBcsType<Uint8Array, Iterable<number>, `bytes[${T}]`>({
+			size,
+			read: (reader) => reader.readBytes(size),
+			write: (value, writer) => {
+				writer.writeBytes(new Uint8Array(value));
+			},
+			...options,
+			name: (options?.name ?? `bytes[${size}]`) as `bytes[${T}]`,
+			validate: (value) => {
+				options?.validate?.(value);
+				if (!value || typeof value !== 'object' || !('length' in value)) {
+					throw new TypeError(`Expected array, found ${typeof value}`);
+				}
+				if (value.length !== size) {
+					throw new TypeError(`Expected array of length ${size}, found ${value.length}`);
+				}
+			},
+		});
+	},
+
+	/**
+	 * Creates a BcsType representing a variable length byte array
+	 *
+	 * @example
+	 * bcs.byteVector().serialize([1, 2, 3]).toBytes() // Uint8Array [3, 1, 2, 3]
+	 */
+	byteVector(options?: BcsTypeOptions<Uint8Array, Iterable<number>>) {
+		return new BcsType<Uint8Array, Iterable<number>, 'vector<u8>'>({
+			read: (reader) => {
+				const length = reader.readULEB();
+
+				return reader.readBytes(length);
+			},
+			write: (value, writer) => {
+				const array = new Uint8Array(value);
+				writer.writeULEB(array.length);
+				writer.writeBytes(array);
+			},
+			...options,
+			name: (options?.name ?? 'vector<u8>') as 'vector<u8>',
+			serializedSize: (value) => {
+				const length = 'length' in value ? (value.length as number) : null;
+				return length == null ? null : ulebEncode(length).length + length;
+			},
+			validate: (value) => {
+				options?.validate?.(value);
+				if (!value || typeof value !== 'object' || !('length' in value)) {
+					throw new TypeError(`Expected array, found ${typeof value}`);
+				}
+			},
+		});
+	},
+
+	/**
+	 * Creates a BcsType that can ser/de string values.  Strings will be UTF-8 encoded
+	 * @example
+	 * bcs.string().serialize('a').toBytes() // Uint8Array [ 1, 97 ]
+	 */
+	string(options?: BcsTypeOptions<string>) {
+		return stringLikeBcsType({
+			toBytes: (value) => new TextEncoder().encode(value),
+			fromBytes: (bytes) => new TextDecoder().decode(bytes),
+			...options,
+			name: (options?.name ?? 'string') as 'string',
+		});
+	},
+	/**
+	 * Creates a BcsType that represents a fixed length array of a given type
+	 * @param size The number of elements in the array
+	 * @param type The BcsType of each element in the array
+	 * @example
+	 * bcs.fixedArray(3, bcs.u8()).serialize([1, 2, 3]).toBytes() // Uint8Array [ 1, 2, 3 ]
+	 */
+	fixedArray,
+
+	/**
+	 * Creates a BcsType representing an optional value
+	 * @param type The BcsType of the optional value
+	 * @example
+	 * bcs.option(bcs.u8()).serialize(null).toBytes() // Uint8Array [ 0 ]
+	 * bcs.option(bcs.u8()).serialize(1).toBytes() // Uint8Array [ 1, 1 ]
+	 */
+	option,
+
+	/**
+	 * Creates a BcsType representing a variable length vector of a given type
+	 * @param type The BcsType of each element in the vector
+	 *
+	 * @example
+	 * bcs.vector(bcs.u8()).toBytes([1, 2, 3]) // Uint8Array [ 3, 1, 2, 3 ]
+	 */
+	vector,
+
+	/**
+	 * Creates a BcsType representing a tuple of a given set of types
+	 * @param types The BcsTypes for each element in the tuple
+	 *
+	 * @example
+	 * const tuple = bcs.tuple([bcs.u8(), bcs.string(), bcs.bool()])
+	 * tuple.serialize([1, 'a', true]).toBytes() // Uint8Array [ 1, 1, 97, 1 ]
+	 */
+	tuple<
+		const T extends readonly BcsType<any, any>[],
+		const Name extends string =
+			`(${JoinString<{ [K in keyof T]: T[K] extends BcsType<any, any, infer T> ? T : never }, ', '>})`,
+	>(
+		fields: T,
+		options?: BcsTypeOptions<
+			{
+				-readonly [K in keyof T]: T[K] extends BcsType<infer T, any> ? T : never;
+			},
+			{
+				[K in keyof T]: T[K] extends BcsType<any, infer T> ? T : never;
+			},
+			Name
+		>,
+	) {
+		return new BcsTuple<T, Name>({
+			fields,
+			...options,
+		});
+	},
+
+	/**
+	 * Creates a BcsType representing a struct of a given set of fields
+	 * @param name The name of the struct
+	 * @param fields The fields of the struct. The order of the fields affects how data is serialized and deserialized
+	 *
+	 * @example
+	 * const struct = bcs.struct('MyStruct', {
+	 *  a: bcs.u8(),
+	 *  b: bcs.string(),
+	 * })
+	 * struct.serialize({ a: 1, b: 'a' }).toBytes() // Uint8Array [ 1, 1, 97 ]
+	 */
+	struct<T extends Record<string, BcsType<any>>, const Name extends string = string>(
+		name: Name,
+		fields: T,
+		options?: Omit<
+			BcsTypeOptions<
+				{
+					[K in keyof T]: T[K] extends BcsType<infer U, any> ? U : never;
+				},
+				{
+					[K in keyof T]: T[K] extends BcsType<any, infer U> ? U : never;
+				}
+			>,
+			'name'
+		>,
+	) {
+		return new BcsStruct<T>({
+			name,
+			fields,
+			...options,
+		});
+	},
+
+	/**
+	 * Creates a BcsType representing an enum of a given set of options
+	 * @param name The name of the enum
+	 * @param values The values of the enum. The order of the values affects how data is serialized and deserialized.
+	 * null can be used to represent a variant with no data.
+	 *
+	 * @example
+	 * const enum = bcs.enum('MyEnum', {
+	 *   A: bcs.u8(),
+	 *   B: bcs.string(),
+	 *   C: null,
+	 * })
+	 * enum.serialize({ A: 1 }).toBytes() // Uint8Array [ 0, 1 ]
+	 * enum.serialize({ B: 'a' }).toBytes() // Uint8Array [ 1, 1, 97 ]
+	 * enum.serialize({ C: true }).toBytes() // Uint8Array [ 2 ]
+	 */
+	enum<T extends Record<string, BcsType<any> | null>, const Name extends string = string>(
+		name: Name,
+		fields: T,
+		options?: Omit<
+			BcsTypeOptions<
+				EnumOutputShape<{
+					[K in keyof T]: T[K] extends BcsType<infer U, any, any> ? U : true;
+				}>,
+				EnumInputShape<{
+					[K in keyof T]: T[K] extends BcsType<any, infer U, any> ? U : boolean | object | null;
+				}>,
+				Name
+			>,
+			'name'
+		>,
+	) {
+		return new BcsEnum<T, Name>({
+			name,
+			fields,
+			...options,
+		});
+	},
+
+	/**
+	 * Creates a BcsType representing a map of a given key and value type
+	 * @param keyType The BcsType of the key
+	 * @param valueType The BcsType of the value
+	 * @example
+	 * const map = bcs.map(bcs.u8(), bcs.string())
+	 * map.serialize(new Map([[2, 'a']])).toBytes() // Uint8Array [ 1, 2, 1, 97 ]
+	 */
+	map,
+
+	/**
+	 * Creates a BcsType that wraps another BcsType which is lazily evaluated. This is useful for creating recursive types.
+	 * @param cb A callback that returns the BcsType
+	 */
+	lazy<T extends BcsType<any>>(cb: () => T): T {
+		return lazyBcsType(cb) as T;
+	},
+};

package/src/index.ts

@@ -0,0 +1,82 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+ * BCS implementation {@see https://github.com/diem/bcs } for JavaScript.
+ * Intended to be used for Move applications; supports both NodeJS and browser.
+ *
+ * For more details and examples {@see README.md }.
+ *
+ * @module bcs
+ * @property {BcsReader}
+ */
+
+import { toBase58, fromBase58, toBase64, fromBase64, toHex, fromHex } from '@haneullabs/utils';
+import type { BcsTypeOptions } from './bcs-type.js';
+import {
+	BcsType,
+	BcsStruct,
+	BcsEnum,
+	BcsTuple,
+	isSerializedBcs,
+	SerializedBcs,
+} from './bcs-type.js';
+import { bcs } from './bcs.js';
+import { BcsReader } from './reader.js';
+import type {
+	EnumInputShape,
+	EnumOutputShape,
+	EnumOutputShapeWithKeys,
+	InferBcsInput,
+	InferBcsType,
+} from './types.js';
+import { decodeStr, encodeStr, splitGenericParameters } from './utils.js';
+import type { BcsWriterOptions } from './writer.js';
+import { BcsWriter } from './writer.js';
+
+// Re-export all encoding dependencies.
+export {
+	bcs,
+	BcsType,
+	BcsStruct,
+	BcsEnum,
+	BcsTuple,
+	type BcsTypeOptions,
+	SerializedBcs,
+	isSerializedBcs,
+	toBase58,
+	fromBase58,
+	toBase64,
+	fromBase64,
+	toHex,
+	fromHex,
+	encodeStr,
+	decodeStr,
+	splitGenericParameters,
+	BcsReader,
+	BcsWriter,
+	type BcsWriterOptions,
+	type InferBcsInput,
+	type InferBcsType,
+	type EnumOutputShape,
+	type EnumInputShape,
+	type EnumOutputShapeWithKeys,
+};
+
+/** @deprecated use toBase58 instead */
+export const toB58 = toBase58;
+
+/** @deprecated use fromBase58 instead */
+export const fromB58 = fromBase58;
+
+/** @deprecated use toBase64 instead */
+export const toB64 = toBase64;
+
+/** @deprecated use fromBase64 instead */
+export const fromB64 = fromBase64;
+
+/** @deprecated use toHex instead */
+export const toHEX = toHex;
+
+/** @deprecated use fromHex instead */
+export const fromHEX = fromHex;