@ckb-lumos/codec
Version:
Make your own molecule binding in JavaScript(TypeScript)
111 lines • 5.39 kB
TypeScript
/**
* | Type | Header | Body |
* |--------+--------------------------------------------------+-----------------------------------|
* | array | | item-0 | item-1 | ... | item-N |
* | struct | | field-0 | field-1 | ... | field-N |
* | fixvec | items-count | item-0 | item-1 | ... | item-N |
* | dynvec | full-size | offset-0 | offset-1 | ... | offset-N | item-0 | item-1 | ... | item-N |
* | table | full-size | offset-0 | offset-1 | ... | offset-N | filed-0 | field-1 | ... | field-N |
* | option | | item or none (zero bytes) |
* | union | item-type-id | item |
*/
import { BytesCodec, Fixed, FixedBytesCodec, PackParam, UnpackResult } from "../base";
type NullableKeys<O extends Record<string, unknown>> = {
[K in keyof O]-?: [O[K] & (undefined | null)] extends [never] ? never : K;
}[keyof O];
type NonNullableKeys<O extends Record<string, unknown>> = {
[K in keyof O]-?: [O[K] & (undefined | null)] extends [never] ? K : never;
}[keyof O];
type PartialNullable<O extends Record<string, unknown>> = Partial<Pick<O, NullableKeys<O>>> & Pick<O, NonNullableKeys<O>>;
/**
* A codec for struct and table of Molecule
*/
export type ObjectLayoutCodec<T extends Record<string, BytesCodec>> = BytesCodec<PartialNullable<{
[key in keyof T]: UnpackResult<T[key]>;
}>, PartialNullable<{
[key in keyof T]: PackParam<T[key]>;
}>>;
/**
* A codec for option of Molecule
*/
export interface OptionLayoutCodec<T extends BytesCodec> extends BytesCodec<UnpackResult<T> | undefined> {
pack: (packable?: PackParam<T>) => Uint8Array;
}
/**
* A code for array and vector of Molecule
*/
export type ArrayLayoutCodec<T extends BytesCodec> = BytesCodec<Array<UnpackResult<T>>, Array<PackParam<T>>>;
/**
* A molecule codec for `
*/
export type UnionLayoutCodec<T extends Record<string, BytesCodec>> = BytesCodec<{
[key in keyof T]: {
type: key;
value: UnpackResult<T[key]>;
};
}[keyof T], {
[key in keyof T]: {
type: key;
value: PackParam<T[key]>;
};
}[keyof T]>;
/**
* The array is a fixed-size type: it has a fixed-size inner type and a fixed length.
* The size of an array is the size of inner type times the length.
* @param itemCodec the fixed-size array item codec
* @param itemCount
*/
export declare function array<T extends FixedBytesCodec>(itemCodec: T, itemCount: number): ArrayLayoutCodec<T> & Fixed;
/**
* Struct is a fixed-size type: all fields in struct are fixed-size and it has a fixed quantity of fields.
* The size of a struct is the sum of all fields' size.
* @param shape a object contains all fields' codec
* @param fields the shape's keys. It provide an order for serialization/deserialization.
*/
export declare function struct<T extends Record<string, FixedBytesCodec>>(shape: T, fields: (keyof T)[]): ObjectLayoutCodec<T> & Fixed;
/**
* Vector with fixed size item codec
* @param itemCodec fixed-size vector item codec
*/
export declare function fixvec<T extends FixedBytesCodec>(itemCodec: T): ArrayLayoutCodec<T>;
/**
* Vector with dynamic size item codec
* @param itemCodec the vector item codec. It can be fixed-size or dynamic-size.
* For example, you can create a recursive vector with this.
*/
export declare function dynvec<T extends BytesCodec>(itemCodec: T): ArrayLayoutCodec<T>;
/**
* General vector codec, if `itemCodec` is fixed size type, it will create a fixvec codec, otherwise a dynvec codec will be created.
* @param itemCodec
*/
export declare function vector<T extends BytesCodec>(itemCodec: T): ArrayLayoutCodec<T>;
/**
* Table is a dynamic-size type. It can be considered as a dynvec but the length is fixed.
* @param shape The table shape, item codec can be dynamic size
* @param fields the shape's keys. Also provide an order for pack/unpack.
*/
export declare function table<T extends Record<string, BytesCodec>>(shape: T, fields: (keyof T)[]): ObjectLayoutCodec<T>;
/**
* Union is a dynamic-size type.
* Serializing a union has two steps:
* - Serialize an item type id in bytes as a 32 bit unsigned integer in little-endian. The item type id is the index of the inner items, and it's starting at 0.
* - Serialize the inner item.
* @param itemCodec the union item record
* @param fields the union item keys, can be an array or an object with custom id
* @example
* // without custom id
* union({ cafe: Uint8, bee: Uint8 }, ['cafe', 'bee'])
* // with custom id
* union({ cafe: Uint8, bee: Uint8 }, { cafe: 0xcafe, bee: 0xbee })
*/
export declare function union<T extends Record<string, BytesCodec>>(itemCodec: T, fields: (keyof T)[] | Record<keyof T, number>): UnionLayoutCodec<T>;
/**
* Option is a dynamic-size type.
* Serializing an option depends on whether it is empty or not:
* - if it's empty, there is zero bytes (the size is 0).
* - if it's not empty, just serialize the inner item (the size is same as the inner item's size).
* @param itemCodec
*/
export declare function option<T extends BytesCodec>(itemCodec: T): OptionLayoutCodec<T>;
export {};
//# sourceMappingURL=layout.d.ts.map