createCodec

Call Signature

function createCodec<TFrom, TTo, TSize>(
    codec,
): FixedSizeCodec<TFrom, TTo, TSize>;

Creates a Codec by filling in the missing encode and decode functions using the provided write and read functions.

This utility combines the behavior of createEncoder and createDecoder to produce a fully functional Codec. The encode method is derived from the write function, while the decode method is derived from the read function.

If the fixedSize property is provided, a FixedSizeCodec will be created, otherwise a VariableSizeCodec will be created.

Type Parameters

Type Parameter	Default type	Description
`TFrom`	-	The type of the value to encode.
`TTo`	`TFrom`	The type of the decoded value.
`TSize` extends `number`	`number`	The fixed size of the encoded value in bytes (for fixed-size codecs).

Parameters

Parameter	Type	Description
`codec`	`Omit`<`FixedSizeCodec`<`TFrom`, `TTo`, `TSize`>, `"decode"` \| `"encode"`>	A codec object that implements `write` and `read`, but not `encode` or `decode`. - If the codec has a `fixedSize` property, it is treated as a FixedSizeCodec. - Otherwise, it is treated as a VariableSizeCodec.

Returns

FixedSizeCodec<TFrom, TTo, TSize>

A fully functional Codec with write, read, encode, and decode methods.

Examples

Creating a custom fixed-size codec.

const codec = createCodec({
    fixedSize: 4,
    read: (bytes, offset) => {
        const value = bytes[offset];
        return [value, offset + 4];
    },
    write: (value: number, bytes, offset) => {
        bytes.set(new Uint8Array([value]), offset);
        return offset + 4;
    },
});
 
const bytes = codec.encode(42);
// 0x2a000000
const value = codec.decode(bytes);
// 42

Creating a custom variable-size codec:

const codec = createCodec({
    getSizeFromValue: (value: string) => value.length,
    read: (bytes, offset) => {
        const decodedValue = new TextDecoder().decode(bytes.subarray(offset));
        return [decodedValue, bytes.length];
    },
    write: (value: string, bytes, offset) => {
        const encodedValue = new TextEncoder().encode(value);
        bytes.set(encodedValue, offset);
        return offset + encodedValue.length;
    },
});
 
const bytes = codec.encode("hello");
// 0x68656c6c6f
const value = codec.decode(bytes);
// "hello"

Remarks

This function effectively combines the behavior of createEncoder and createDecoder. If you only need to encode or decode (but not both), consider using those functions instead.

Here are some alternative examples using codec primitives instead of createCodec.

// Fixed-size codec for unsigned 32-bit integers.
const codec = getU32Codec();
const bytes = codec.encode(42);
// 0x2a000000
const value = codec.decode(bytes);
// 42
 
// Variable-size codec for 32-bytes prefixed UTF-8 strings.
const codec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
const bytes = codec.encode("hello");
// 0x0500000068656c6c6f
const value = codec.decode(bytes);
// "hello"
 
// Variable-size codec for custom objects.
type Person = { name: string; age: number };
const codec: Codec<PersonInput, Person> = getStructCodec([
    ['name', addCodecSizePrefix(getUtf8Codec(), getU32Codec())],
    ['age', getU32Codec()],
]);
const bytes = codec.encode({ name: "Bob", age: 42 });
// 0x03000000426f622a000000
const value = codec.decode(bytes);
// { name: "Bob", age: 42 }

See

Call Signature

function createCodec<TFrom, TTo>(codec): VariableSizeCodec<TFrom, TTo>;

Creates a Codec by filling in the missing encode and decode functions using the provided write and read functions.

If the fixedSize property is provided, a FixedSizeCodec will be created, otherwise a VariableSizeCodec will be created.

Type Parameters

Type Parameter	Default type	Description
`TFrom`	-	The type of the value to encode.
`TTo`	`TFrom`	The type of the decoded value.

Parameters

Parameter	Type	Description
`codec`	`Omit`<`VariableSizeCodec`<`TFrom`, `TTo`>, `"decode"` \| `"encode"`>	A codec object that implements `write` and `read`, but not `encode` or `decode`. - If the codec has a `fixedSize` property, it is treated as a FixedSizeCodec. - Otherwise, it is treated as a VariableSizeCodec.

Returns

VariableSizeCodec<TFrom, TTo>

A fully functional Codec with write, read, encode, and decode methods.

Examples

Creating a custom fixed-size codec.

const codec = createCodec({
    fixedSize: 4,
    read: (bytes, offset) => {
        const value = bytes[offset];
        return [value, offset + 4];
    },
    write: (value: number, bytes, offset) => {
        bytes.set(new Uint8Array([value]), offset);
        return offset + 4;
    },
});
 
const bytes = codec.encode(42);
// 0x2a000000
const value = codec.decode(bytes);
// 42

Creating a custom variable-size codec:

const codec = createCodec({
    getSizeFromValue: (value: string) => value.length,
    read: (bytes, offset) => {
        const decodedValue = new TextDecoder().decode(bytes.subarray(offset));
        return [decodedValue, bytes.length];
    },
    write: (value: string, bytes, offset) => {
        const encodedValue = new TextEncoder().encode(value);
        bytes.set(encodedValue, offset);
        return offset + encodedValue.length;
    },
});
 
const bytes = codec.encode("hello");
// 0x68656c6c6f
const value = codec.decode(bytes);
// "hello"

Remarks

This function effectively combines the behavior of createEncoder and createDecoder. If you only need to encode or decode (but not both), consider using those functions instead.

Here are some alternative examples using codec primitives instead of createCodec.

// Fixed-size codec for unsigned 32-bit integers.
const codec = getU32Codec();
const bytes = codec.encode(42);
// 0x2a000000
const value = codec.decode(bytes);
// 42
 
// Variable-size codec for 32-bytes prefixed UTF-8 strings.
const codec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
const bytes = codec.encode("hello");
// 0x0500000068656c6c6f
const value = codec.decode(bytes);
// "hello"
 
// Variable-size codec for custom objects.
type Person = { name: string; age: number };
const codec: Codec<PersonInput, Person> = getStructCodec([
    ['name', addCodecSizePrefix(getUtf8Codec(), getU32Codec())],
    ['age', getU32Codec()],
]);
const bytes = codec.encode({ name: "Bob", age: 42 });
// 0x03000000426f622a000000
const value = codec.decode(bytes);
// { name: "Bob", age: 42 }

See

Call Signature

function createCodec<TFrom, TTo>(codec): Codec<TFrom, TTo>;

Creates a Codec by filling in the missing encode and decode functions using the provided write and read functions.

If the fixedSize property is provided, a FixedSizeCodec will be created, otherwise a VariableSizeCodec will be created.

Type Parameters

Type Parameter	Default type	Description
`TFrom`	-	The type of the value to encode.
`TTo`	`TFrom`	The type of the decoded value.

Parameters

Parameter	Type	Description
`codec`	\| `Omit`<`FixedSizeCodec`<`TFrom`, `TTo`, `number`>, `"encode"` \| `"decode"`> \| `Omit`<`VariableSizeCodec`<`TFrom`, `TTo`>, `"encode"` \| `"decode"`>	A codec object that implements `write` and `read`, but not `encode` or `decode`. - If the codec has a `fixedSize` property, it is treated as a FixedSizeCodec. - Otherwise, it is treated as a VariableSizeCodec.

Returns

Codec<TFrom, TTo>

A fully functional Codec with write, read, encode, and decode methods.

Examples

Creating a custom fixed-size codec.

const codec = createCodec({
    fixedSize: 4,
    read: (bytes, offset) => {
        const value = bytes[offset];
        return [value, offset + 4];
    },
    write: (value: number, bytes, offset) => {
        bytes.set(new Uint8Array([value]), offset);
        return offset + 4;
    },
});
 
const bytes = codec.encode(42);
// 0x2a000000
const value = codec.decode(bytes);
// 42

Creating a custom variable-size codec:

const codec = createCodec({
    getSizeFromValue: (value: string) => value.length,
    read: (bytes, offset) => {
        const decodedValue = new TextDecoder().decode(bytes.subarray(offset));
        return [decodedValue, bytes.length];
    },
    write: (value: string, bytes, offset) => {
        const encodedValue = new TextEncoder().encode(value);
        bytes.set(encodedValue, offset);
        return offset + encodedValue.length;
    },
});
 
const bytes = codec.encode("hello");
// 0x68656c6c6f
const value = codec.decode(bytes);
// "hello"

Remarks

This function effectively combines the behavior of createEncoder and createDecoder. If you only need to encode or decode (but not both), consider using those functions instead.

Here are some alternative examples using codec primitives instead of createCodec.

// Fixed-size codec for unsigned 32-bit integers.
const codec = getU32Codec();
const bytes = codec.encode(42);
// 0x2a000000
const value = codec.decode(bytes);
// 42
 
// Variable-size codec for 32-bytes prefixed UTF-8 strings.
const codec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
const bytes = codec.encode("hello");
// 0x0500000068656c6c6f
const value = codec.decode(bytes);
// "hello"
 
// Variable-size codec for custom objects.
type Person = { name: string; age: number };
const codec: Codec<PersonInput, Person> = getStructCodec([
    ['name', addCodecSizePrefix(getUtf8Codec(), getU32Codec())],
    ['age', getU32Codec()],
]);
const bytes = codec.encode({ name: "Bob", age: 42 });
// 0x03000000426f622a000000
const value = codec.decode(bytes);
// { name: "Bob", age: 42 }

createCodec

On this page