@haneullabs/bcs 0.1.0

package/README.md

@@ -0,0 +1,358 @@
+# BCS - Binary Canonical Serialization
+
+This small and lightweight library implements
+[Binary Canonical Serialization (BCS)](https://github.com/zefchain/bcs) in TypeScript, making BCS
+available in both Browser and NodeJS environments in a type-safe way.`
+
+## Install
+
+To install, add the [`@haneullabs/bcs`](https://www.npmjs.com/package/@haneullabs/bcs) package to your
+project:
+
+```sh npm2yarn
+npm i @haneullabs/bcs
+```
+
+## Quickstart
+
+```ts
+import { bcs, fromHex, toHex } from '@haneullabs/bcs';
+
+// define UID as a 32-byte array, then add a transform to/from hex strings
+const UID = bcs.fixedArray(32, bcs.u8()).transform({
+	input: (id: string) => fromHex(id),
+	output: (id) => toHex(Uint8Array.from(id)),
+});
+
+const Coin = bcs.struct('Coin', {
+	id: UID,
+	value: bcs.u64(),
+});
+
+// deserialization: BCS bytes into Coin
+const bcsBytes = Coin.serialize({
+	id: '0000000000000000000000000000000000000000000000000000000000000001',
+	value: 1000000n,
+}).toBytes();
+
+const coin = Coin.parse(bcsBytes);
+
+// serialization: Object into bytes - an Option with <T = Coin>
+const hex = bcs.option(Coin).serialize(coin).toHex();
+
+console.log(hex);
+```
+
+## Description
+
+BCS defines the way the data is serialized, and the serialized results contains no type information.
+To be able to serialize the data and later deserialize it, a schema has to be created (based on the
+built-in primitives, such as `string` or `u64`). There are no type hints in the serialized bytes on
+what they mean, so the schema used for decoding must match the schema used to encode the data.
+
+The `@haneullabs/bcs` library can be used to define schemas that can serialize and deserialize BCS
+encoded data, and can infer the correct TypeScript for the schema from the definitions themselves
+rather than having to define them manually.
+
+## Basic types
+
+bcs supports a number of built in base types that can be combined to create more complex types. The
+following table lists the primitive types available:
+
+| Method                | TS Type      | TS Input Type                | Description                                                                 |
+| --------------------- | ------------ | ---------------------------- | --------------------------------------------------------------------------- |
+| `bool`                | `boolean`    | `boolean`                    | Boolean type (converts to `true` / `false`)                                 |
+| `u8`, `u16`, `u32`    | `number`     | `number`                     | Unsigned Integer types                                                      |
+| `u64`, `u128`, `u256` | `string`     | `number \| string \| bigint` | Unsigned Integer types, decoded as `string` to allow for JSON serialization |
+| `uleb128`             | `number`     | `number`                     | Unsigned LEB128 integer type                                                |
+| `string`              | `string`     | `string`                     | UTF-8 encoded string                                                        |
+| `bytes(size)`         | `Uint8Array` | `Iterable<number>`           | Fixed length bytes                                                          |
+
+```ts
+import { bcs } from '@haneullabs/bcs';
+
+// Integers
+const u8 = bcs.u8().serialize(100).toBytes();
+const u64 = bcs.u64().serialize(1000000n).toBytes();
+const u128 = bcs.u128().serialize('100000010000001000000').toBytes();
+
+// Other types
+const str = bcs.string().serialize('this is an ascii string').toBytes();
+const hex = bcs.hex().serialize('C0FFEE').toBytes();
+const bytes = bcs.bytes(4).serialize([1, 2, 3, 4]).toBytes();
+
+// Parsing data back into original types
+const parsedU8 = bcs.u8().parse(u8);
+// u64-u256 will be represented as bigints regardless of how they were provided when serializing them
+const parsedU64 = bcs.u64().parse(u64);
+const parsedU128 = bcs.u128().parse(u128);
+
+const parsedStr = bcs.string().parse(str);
+const parsedHex = bcs.hex().parse(hex);
+const parsedBytes = bcs.bytes(4).parse(bytes);
+```
+
+## Compound types
+
+For most use-cases you'll want to combine primitive types into more complex types like `vectors`,
+`structs` and `enums`. The following table lists methods available for creating compound types:
+
+| Method                 | Description                                           |
+| ---------------------- | ----------------------------------------------------- |
+| `vector(type: T)`      | A variable length list of values of type `T`          |
+| `fixedArray(size, T)`  | A fixed length array of values of type `T`            |
+| `option(type: T)`      | A value of type `T` or `null`                         |
+| `enum(name, values)`   | An enum value representing one of the provided values |
+| `struct(name, fields)` | A struct with named fields of the provided types      |
+| `tuple(types)`         | A tuple of the provided types                         |
+| `map(K, V)`            | A map of keys of type `K` to values of type `V`       |
+
+```ts
+import { bcs } from '@haneullabs/bcs';
+
+// Vectors
+const intList = bcs.vector(bcs.u8()).serialize([1, 2, 3, 4, 5]).toBytes();
+const stringList = bcs.vector(bcs.string()).serialize(['a', 'b', 'c']).toBytes();
+
+// Fixed length Arrays
+const intArray = bcs.fixedArray(4, bcs.u8()).serialize([1, 2, 3, 4]).toBytes();
+const stringArray = bcs.fixedArray(3, bcs.string()).serialize(['a', 'b', 'c']).toBytes();
+
+// Option
+const option = bcs.option(bcs.string()).serialize('some value').toBytes();
+const nullOption = bcs.option(bcs.string()).serialize(null).toBytes();
+
+// Enum
+const MyEnum = bcs.enum('MyEnum', {
+	NoType: null,
+	Int: bcs.u8(),
+	String: bcs.string(),
+	Array: bcs.fixedArray(3, bcs.u8()),
+});
+
+const noTypeEnum = MyEnum.serialize({ NoType: null }).toBytes();
+const intEnum = MyEnum.serialize({ Int: 100 }).toBytes();
+const stringEnum = MyEnum.serialize({ String: 'string' }).toBytes();
+const arrayEnum = MyEnum.serialize({ Array: [1, 2, 3] }).toBytes();
+
+// Struct
+const MyStruct = bcs.struct('MyStruct', {
+	id: bcs.u8(),
+	name: bcs.string(),
+});
+
+const struct = MyStruct.serialize({ id: 1, name: 'name' }).toBytes();
+
+// Tuple
+const tuple = bcs.tuple([bcs.u8(), bcs.string()]).serialize([1, 'name']).toBytes();
+
+// Map
+const map = bcs
+	.map(bcs.u8(), bcs.string())
+	.serialize(
+		new Map([
+			[1, 'one'],
+			[2, 'two'],
+		]),
+	)
+	.toBytes();
+
+// Parsing data back into original types
+
+// Vectors
+const parsedIntList = bcs.vector(bcs.u8()).parse(intList);
+const parsedStringList = bcs.vector(bcs.string()).parse(stringList);
+
+// Fixed length Arrays
+const parsedIntArray = bcs.fixedArray(4, bcs.u8()).parse(intArray);
+
+// Option
+const parsedOption = bcs.option(bcs.string()).parse(option);
+const parsedNullOption = bcs.option(bcs.string()).parse(nullOption);
+
+// Enum
+const parsedNoTypeEnum = MyEnum.parse(noTypeEnum);
+const parsedIntEnum = MyEnum.parse(intEnum);
+const parsedStringEnum = MyEnum.parse(stringEnum);
+const parsedArrayEnum = MyEnum.parse(arrayEnum);
+
+// Struct
+const parsedStruct = MyStruct.parse(struct);
+
+// Tuple
+const parsedTuple = bcs.tuple([bcs.u8(), bcs.string()]).parse(tuple);
+
+// Map
+const parsedMap = bcs.map(bcs.u8(), bcs.string()).parse(map);
+```
+
+## Generics
+
+To define a generic struct or an enum, you can define a generic typescript function helper
+
+```ts
+// Example: Generics
+import { bcs, BcsType } from '@haneullabs/bcs';
+
+// The T typescript generic is a placeholder for the typescript type of the generic value
+// The T argument will be the bcs type passed in when creating a concrete instance of the Container type
+function Container<T>(T: BcsType<T>) {
+	return bcs.struct('Container<T>', {
+		contents: T,
+	}),
+}
+
+// When serializing, we have to pass the type to use for `T`
+const bytes = Container(bcs.u8()).serialize({ contents: 100 }).toBytes();
+
+// Alternatively we can save the concrete type as a variable
+const U8Container = Container(bcs.u8());
+const bytes = U8Container.serialize({ contents: 100 }).toBytes();
+
+// Using multiple generics
+function VecMap<K, V>, (K: BcsType<K>, V: BcsType<V>) {
+	// You can use the names of the generic params in the type name to
+	return bcs.struct(
+		// You can use the names of the generic params to give your type a more useful name
+		`VecMap<${K.name}, ${V.name}>`,
+		{
+			keys: bcs.vector(K),
+			values: bcs.vector(V),
+		}
+	)
+}
+
+// To serialize VecMap, we can use:
+VecMap(bcs.string(), bcs.string())
+	.serialize({
+		keys: ['key1', 'key2', 'key3'],
+		values: ['value1', 'value2', 'value3'],
+	})
+	.toBytes();
+```
+
+## Transforms
+
+If the format you use in your code is different from the format expected for BCS serialization, you
+can use the `transform` API to map between the types you use in your application, and the types
+needed for serialization.
+
+The `address` type used by Move code is a good example of this. In many cases, you'll want to
+represent an address as a hex string, but the BCS serialization format for addresses is a 32 byte
+array. To handle this, you can use the `transform` API to map between the two formats:
+
+```ts
+import { bcs, toHex } from '@haneullabs/bcs';
+
+const Address = bcs.bytes(32).transform({
+	// To change the input type, you need to provide a type definition for the input
+	input: (val: string) => fromHex(val),
+	output: (val) => toHex(val),
+});
+
+const serialized = Address.serialize('0x000000...').toBytes();
+const parsed = Address.parse(serialized); // will return a hex string
+```
+
+When using a transform, a new type is created that uses the inferred return value of `output` as the
+return type of the `parse` method, and the type of the `input` argument as the allowed input type
+when calling `serialize`. The `output` type can generally be inferred from the definition, but the
+input type will need to be provided explicitly. In some cases, for complex transforms, you'll need
+to manually type the return
+
+transforms can also handle more complex types. For instance, `@haneullabs/haneul` uses the following
+definition to transform enums into a more TypeScript friends format:
+
+```ts
+type Merge<T> = T extends infer U ? { [K in keyof U]: U[K] } : never;
+type EnumKindTransform<T> = T extends infer U
+	? Merge<(U[keyof U] extends null | boolean ? object : U[keyof U]) & { kind: keyof U }>
+	: never;
+
+function enumKind<T extends object, Input extends object>(type: BcsType<T, Input>) {
+	return type.transform({
+		input: ({ kind, ...val }: EnumKindTransform<Input>) =>
+			({
+				[kind]: val,
+			}) as Input,
+		output: (val) => {
+			const key = Object.keys(val)[0] as keyof T;
+
+			return { kind: key, ...val[key] } as EnumKindTransform<T>;
+		},
+	});
+}
+
+const MyEnum = enumKind(
+	bcs.enum('MyEnum', {
+		A: bcs.struct('A', {
+			id: bcs.u8(),
+		}),
+		B: bcs.struct('B', {
+			val: bcs.string(),
+		}),
+	}),
+);
+
+// Enums wrapped with enumKind flatten the enum variants and add a `kind` field to differentiate them
+const A = MyEnum.serialize({ kind: 'A', id: 1 }).toBytes();
+const B = MyEnum.serialize({ kind: 'B', val: 'xyz' }).toBytes();
+
+const parsedA = MyEnum.parse(A); // returns { kind: 'A', id: 1 }
+```
+
+## Formats for serialized bytes
+
+When you call `serialize` on a `BcsType`, you will receive a `SerializedBcs` instance. This wrapper
+preserves type information for the serialized bytes, and can be used to get raw data in various
+formats.
+
+```ts
+import { bcs, fromBase58, fromBase64, fromHex } from '@haneullabs/bcs';
+
+const serializedString = bcs.string().serialize('this is a string');
+
+// SerializedBcs.toBytes() returns a Uint8Array
+const bytes: Uint8Array = serializedString.toBytes();
+
+// You can get the serialized bytes encoded as hex, base64 or base58
+const hex: string = serializedString.toHex();
+const base64: string = bcsWriter.toBase64();
+const base58: string = bcsWriter.toBase58();
+
+// To parse a BCS value from bytes, the bytes need to be a Uint8Array
+const str1 = bcs.string().parse(bytes);
+
+// If your data is encoded as string, you need to convert it to Uint8Array first
+const str2 = bcs.string().parse(fromHex(hex));
+const str3 = bcs.string().parse(fromBase64(base64));
+const str4 = bcs.string().parse(fromBase58(base58));
+
+console.assert((str1 == str2) == (str3 == str4), 'Result is the same');
+```
+
+## Inferring types
+
+BCS types have both a `type` and an `inputType`. For some types these are the same, but for others
+(like `u64`) the types diverge slightly to make inputs more flexible. For instance, `u64` will
+always be `string` for it's type, but can be a `number`, `string` or `bigint` for it's input type.
+
+You can infer these types in one of 2 ways, either using the `$inferType` and `$inferInput`
+properties on a `BcsType`, or using the `InferBcsType` and `InferBcsInput` type helpers.
+
+```ts
+import { bcs, type InferBcsType, type InferBcsInput } from '@haneullabs/bcs';
+
+const MyStruct = bcs.struct('MyStruct', {
+	id: bcs.u64(),
+	name: bcs.string(),
+});
+
+// using the $inferType and $inferInput properties
+type MyStructType = typeof MyStruct.$inferType; // { id: string; name: string; }
+type MyStructInput = typeof MyStruct.$inferInput; // { id: number | string | bigint; name: string; }
+
+// using the InferBcsType and InferBcsInput type helpers
+type MyStructType = InferBcsType<typeof MyStruct>; // { id: string; name: string; }
+type MyStructInput = InferBcsInput<typeof MyStruct>; // { id: number | string | bigint; name: string; }
+```

package/dist/cjs/bcs-type.d.ts

@@ -0,0 +1,127 @@
+import { BcsReader } from './reader.js';
+import type { BcsWriterOptions } from './writer.js';
+import { BcsWriter } from './writer.js';
+import type { EnumInputShape, EnumOutputShape, JoinString } from './types.js';
+export interface BcsTypeOptions<T, Input = T, Name extends string = string> {
+    name?: Name;
+    validate?: (value: Input) => void;
+}
+export declare class BcsType<T, Input = T, const Name extends string = string> {
+    #private;
+    $inferType: T;
+    $inferInput: Input;
+    name: Name;
+    read: (reader: BcsReader) => T;
+    serializedSize: (value: Input, options?: BcsWriterOptions) => number | null;
+    validate: (value: Input) => void;
+    constructor(options: {
+        name: Name;
+        read: (reader: BcsReader) => T;
+        write: (value: Input, writer: BcsWriter) => void;
+        serialize?: (value: Input, options?: BcsWriterOptions) => Uint8Array<ArrayBuffer>;
+        serializedSize?: (value: Input) => number | null;
+        validate?: (value: Input) => void;
+    } & BcsTypeOptions<T, Input, Name>);
+    write(value: Input, writer: BcsWriter): void;
+    serialize(value: Input, options?: BcsWriterOptions): SerializedBcs<T, Input>;
+    parse(bytes: Uint8Array): T;
+    fromHex(hex: string): T;
+    fromBase58(b64: string): T;
+    fromBase64(b64: string): T;
+    transform<T2 = T, Input2 = Input, NewName extends string = Name>({ name, input, output, validate, }: {
+        input?: (val: Input2) => Input;
+        output?: (value: T) => T2;
+    } & BcsTypeOptions<T2, Input2, NewName>): BcsType<T2, Input2, NewName>;
+}
+declare const SERIALIZED_BCS_BRAND: never;
+export declare function isSerializedBcs(obj: unknown): obj is SerializedBcs<unknown>;
+export declare class SerializedBcs<T, Input = T> {
+    #private;
+    [SERIALIZED_BCS_BRAND]: boolean;
+    constructor(schema: BcsType<T, Input>, bytes: Uint8Array<ArrayBuffer>);
+    toBytes(): Uint8Array<ArrayBuffer>;
+    toHex(): string;
+    toBase64(): string;
+    toBase58(): string;
+    parse(): T;
+}
+export declare function fixedSizeBcsType<T, Input = T, const Name extends string = string>({ size, ...options }: {
+    name: Name;
+    size: number;
+    read: (reader: BcsReader) => T;
+    write: (value: Input, writer: BcsWriter) => void;
+} & BcsTypeOptions<T, Input, Name>): BcsType<T, Input, Name>;
+export declare function uIntBcsType<const Name extends string = string>({ readMethod, writeMethod, ...options }: {
+    name: Name;
+    size: number;
+    readMethod: `read${8 | 16 | 32}`;
+    writeMethod: `write${8 | 16 | 32}`;
+    maxValue: number;
+} & BcsTypeOptions<number, number, Name>): BcsType<number, number, Name>;
+export declare function bigUIntBcsType<const Name extends string = string>({ readMethod, writeMethod, ...options }: {
+    name: Name;
+    size: number;
+    readMethod: `read${64 | 128 | 256}`;
+    writeMethod: `write${64 | 128 | 256}`;
+    maxValue: bigint;
+} & BcsTypeOptions<string, string | number | bigint>): BcsType<string, string | number | bigint, Name>;
+export declare function dynamicSizeBcsType<T, Input = T, const Name extends string = string>({ serialize, ...options }: {
+    name: Name;
+    read: (reader: BcsReader) => T;
+    serialize: (value: Input, options?: BcsWriterOptions) => Uint8Array<ArrayBuffer>;
+} & BcsTypeOptions<T, Input>): BcsType<T, Input, string>;
+export declare function stringLikeBcsType<const Name extends string = string>({ toBytes, fromBytes, ...options }: {
+    name: Name;
+    toBytes: (value: string) => Uint8Array;
+    fromBytes: (bytes: Uint8Array) => string;
+    serializedSize?: (value: string) => number | null;
+} & BcsTypeOptions<string, string, Name>): BcsType<string, string, Name>;
+export declare function lazyBcsType<T, Input>(cb: () => BcsType<T, Input>): BcsType<T, Input, string>;
+export interface BcsStructOptions<T extends Record<string, BcsType<any>>, Name extends string = string> extends 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>, 'name'> {
+    name: Name;
+    fields: T;
+}
+export declare class BcsStruct<T extends Record<string, BcsType<any>>, const Name extends string = string> extends BcsType<{
+    [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> {
+    constructor({ name, fields, ...options }: BcsStructOptions<T, Name>);
+}
+export interface BcsEnumOptions<T extends Record<string, BcsType<any> | null>, Name extends string = string> extends 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'> {
+    name: Name;
+    fields: T;
+}
+export declare class BcsEnum<T extends Record<string, BcsType<any> | null>, const Name extends string = string> extends BcsType<EnumOutputShape<{
+    [K in keyof T]: T[K] extends BcsType<infer U, any> ? U : true;
+}>, EnumInputShape<{
+    [K in keyof T]: T[K] extends BcsType<any, infer U, any> ? U : boolean | object | null;
+}>, Name> {
+    constructor({ fields, ...options }: BcsEnumOptions<T, Name>);
+}
+export interface BcsTupleOptions<T extends readonly BcsType<any>[], Name extends string> extends Omit<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>, 'name'> {
+    name?: Name;
+    fields: T;
+}
+export declare class BcsTuple<const T extends readonly BcsType<any>[], const Name extends string = `(${JoinString<{
+    [K in keyof T]: T[K] extends BcsType<any, any, infer T> ? T : never;
+}, ', '>})`> extends BcsType<{
+    -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> {
+    constructor({ fields, name, ...options }: BcsTupleOptions<T, Name>);
+}
+export {};