refactor(experimental): add FixedSizeCodec and VariableSizeCodec types (#1883)

This PR slightly refactors the type definitions of `Encoders`, `Decoders` and `Codecs` by providing a `FixedSize*` and `VariableSize*` type variant for each of them.

This allows us to provide type safety when codec factories expect fixed size or variable size codecs. For instance, `reverseEncoder({} as VariableSizeEncoder<string>)` will now throw a TypeScript error as the `reverseEncoder<T>()` function expects a `FixedSizeEncoder<T>`.

Author: lorisleiva

packages/codecs-core/src/__tests__/reverse-codec-test.ts

@@ -1,4 +1,4 @@
-import { createDecoder, createEncoder, Decoder, Encoder } from '../codec';
+import { createDecoder, createEncoder } from '../codec';
 import { fixCodec } from '../fix-codec';
 import { reverseCodec, reverseDecoder, reverseEncoder } from '../reverse-codec';
 import { b, base16 } from './__setup__';
@@ -27,13 +27,14 @@ describe('reverseCodec', () => {
         expect(s(4).read(b('aaaa00000001bbbb'), 2)).toStrictEqual(['01000000', 6]);
 
         // Variable-size codec.
+        // @ts-expect-error Reversed codec should be fixed-size.
         expect(() => reverseCodec(base16)).toThrow('Cannot reverse a codec of variable size');
     });
 });
 
 describe('reverseEncoder', () => {
     it('can reverse the bytes of a fixed-size encoder', () => {
-        const encoder: Encoder<number> = createEncoder({
+        const encoder = createEncoder({
             fixedSize: 2,
             write: (value: number, bytes, offset) => {
                 bytes.set([value, 0], offset);
@@ -44,20 +45,24 @@ describe('reverseEncoder', () => {
         const reversedEncoder = reverseEncoder(encoder);
         expect(reversedEncoder.fixedSize).toBe(2);
         expect(reversedEncoder.encode(42)).toStrictEqual(new Uint8Array([0, 42]));
+
+        // @ts-expect-error Reversed encoder should be fixed-size.
         expect(() => reverseEncoder(base16)).toThrow('Cannot reverse a codec of variable size');
     });
 });
 
 describe('reverseDecoder', () => {
     it('can reverse the bytes of a fixed-size decoder', () => {
-        const decoder: Decoder<string> = createDecoder({
+        const decoder = createDecoder({
             fixedSize: 2,
             read: (bytes: Uint8Array, offset = 0) => [`${bytes[offset]}-${bytes[offset + 1]}`, offset + 2],
         });
 
         const reversedDecoder = reverseDecoder(decoder);
         expect(reversedDecoder.fixedSize).toBe(2);
         expect(reversedDecoder.read(new Uint8Array([42, 0]), 0)).toStrictEqual(['0-42', 2]);
+
+        // @ts-expect-error Reversed decoder should be fixed-size.
         expect(() => reverseDecoder(base16)).toThrow('Cannot reverse a codec of variable size');
     });
 });

packages/codecs-core/src/__typetests__/codec-typetest.ts

@@ -0,0 +1,57 @@
+import {
+    Codec,
+    createCodec,
+    createDecoder,
+    createEncoder,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '../codec';
+
+{
+    // [createEncoder]: It knows if the encoder is fixed size or variable size.
+    createEncoder({
+        fixedSize: 42,
+        write: (_: string) => 1,
+    }) satisfies FixedSizeEncoder<string>;
+    createEncoder({
+        fixedSize: null,
+        variableSize: (_: string) => 42,
+        write: (_: string) => 1,
+    }) satisfies VariableSizeEncoder<string>;
+    createEncoder({} as Encoder<string>) satisfies Encoder<string>;
+}
+
+{
+    // [createDecoder]: It knows if the decoder is fixed size or variable size.
+    createDecoder({
+        fixedSize: 42,
+        read: (): [string, number] => ['', 1],
+    }) satisfies FixedSizeDecoder<string>;
+    createDecoder({
+        fixedSize: null,
+        read: (): [string, number] => ['', 1],
+    }) satisfies VariableSizeDecoder<string>;
+    createDecoder({} as Decoder<string>) satisfies Decoder<string>;
+}
+
+{
+    // [createCodec]: It knows if the codec is fixed size or variable size.
+    createCodec({
+        fixedSize: 42,
+        read: (): [string, number] => ['', 1],
+        write: (_: string) => 1,
+    }) satisfies FixedSizeCodec<string>;
+    createCodec({
+        fixedSize: null,
+        read: (): [string, number] => ['', 1],
+        variableSize: (_: string) => 42,
+        write: (_: string) => 1,
+    }) satisfies VariableSizeCodec<string>;
+    createCodec({} as Codec<string>) satisfies Codec<string>;
+}

packages/codecs-core/src/__typetests__/combine-codec-typetest.ts

@@ -0,0 +1,45 @@
+import {
+    Codec,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '../codec';
+import { combineCodec } from '../combine-codec';
+
+{
+    // [combineCodec]: It keeps track of the fixed or variable size types.
+    combineCodec({} as FixedSizeEncoder<string>, {} as FixedSizeDecoder<string>) satisfies FixedSizeCodec<string>;
+    combineCodec(
+        {} as VariableSizeEncoder<string>,
+        {} as VariableSizeDecoder<string>
+    ) satisfies VariableSizeCodec<string>;
+    combineCodec({} as Encoder<string>, {} as Decoder<string>) satisfies Codec<string>;
+}
+
+{
+    // [combineCodec]: It authorizes From and To types that such that To extends From.
+    combineCodec({} as Encoder<number | bigint>, {} as Decoder<bigint>) satisfies Codec<number | bigint, bigint>;
+    combineCodec({} as Encoder<{ name: string }>, {} as Decoder<{ name: string; age: number }>) satisfies Codec<
+        { name: string },
+        { name: string; age: number }
+    >;
+}
+
+{
+    // [combineCodec]: It forbids From and To types that are not compatible.
+    // @ts-expect-error Expected a number decoder or a string encoder.
+    combineCodec({} as Encoder<number>, {} as Decoder<string>) satisfies Codec<string>;
+    // @ts-expect-error number | bigint is not assignable to bigint.
+    combineCodec({} as Encoder<bigint>, {} as Decoder<number | bigint>) satisfies Codec<bigint, number | bigint>;
+    // @ts-expect-error The decoded value does not extend the encoded value.
+    combineCodec({} as Encoder<{ name: string; age: number }>, {} as Decoder<{ name: string }>) satisfies Codec<
+        { name: string; age: number },
+        // @ts-expect-error Age property is missing.
+        { name: string }
+    >;
+}

packages/codecs-core/src/__typetests__/fix-codec-typetest.ts

@@ -0,0 +1,33 @@
+import {
+    Codec,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '../codec';
+import { fixCodec, fixDecoder, fixEncoder } from '../fix-codec';
+
+{
+    // [fixEncoder]: It transforms any encoder into a fixed size encoder.
+    fixEncoder({} as FixedSizeEncoder<string>, 42) satisfies FixedSizeEncoder<string>;
+    fixEncoder({} as VariableSizeEncoder<string>, 42) satisfies FixedSizeEncoder<string>;
+    fixEncoder({} as Encoder<string>, 42) satisfies FixedSizeEncoder<string>;
+}
+
+{
+    // [fixDecoder]: It transforms any decoder into a fixed size decoder.
+    fixDecoder({} as FixedSizeDecoder<string>, 42) satisfies FixedSizeDecoder<string>;
+    fixDecoder({} as VariableSizeDecoder<string>, 42) satisfies FixedSizeDecoder<string>;
+    fixDecoder({} as Decoder<string>, 42) satisfies FixedSizeDecoder<string>;
+}
+
+{
+    // [fixCodec]: It transforms any codec into a fixed size codec.
+    fixCodec({} as FixedSizeCodec<string>, 42) satisfies FixedSizeCodec<string>;
+    fixCodec({} as VariableSizeCodec<string>, 42) satisfies FixedSizeCodec<string>;
+    fixCodec({} as Codec<string>, 42) satisfies FixedSizeCodec<string>;
+}

packages/codecs-core/src/__typetests__/map-codec-typetest.ts

@@ -0,0 +1,45 @@
+import {
+    Codec,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '../codec';
+import { mapCodec, mapDecoder, mapEncoder } from '../map-codec';
+
+{
+    // [mapEncoder]: It keeps track of the nested encoder's size.
+    mapEncoder({} as FixedSizeEncoder<string>, (_: number) => '42') satisfies FixedSizeEncoder<number>;
+    mapEncoder({} as VariableSizeEncoder<string>, (_: number) => '42') satisfies VariableSizeEncoder<number>;
+    mapEncoder({} as Encoder<string>, (_: number) => '42') satisfies Encoder<number>;
+}
+
+{
+    // [mapDecoder]: It keeps track of the nested decoder's size.
+    mapDecoder({} as FixedSizeDecoder<string>, (_: string) => 42) satisfies FixedSizeDecoder<number>;
+    mapDecoder({} as VariableSizeDecoder<string>, (_: string) => 42) satisfies VariableSizeDecoder<number>;
+    mapDecoder({} as Decoder<string>, (_: string) => 42) satisfies Decoder<number>;
+}
+
+{
+    // [mapCodec]: It keeps track of the nested codec's size.
+    mapCodec(
+        {} as FixedSizeCodec<string>,
+        (_: number) => '42',
+        (_: string) => 42
+    ) satisfies FixedSizeCodec<number>;
+    mapCodec(
+        {} as VariableSizeCodec<string>,
+        (_: number) => '42',
+        (_: string) => 42
+    ) satisfies VariableSizeCodec<number>;
+    mapCodec(
+        {} as Codec<string>,
+        (_: number) => '42',
+        (_: string) => 42
+    ) satisfies Codec<number>;
+}

packages/codecs-core/src/__typetests__/reverse-codec-typetest.ts

@@ -0,0 +1,39 @@
+import {
+    Codec,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '../codec';
+import { reverseCodec, reverseDecoder, reverseEncoder } from '../reverse-codec';
+
+{
+    // [reverseEncoder]: It only works with fixed size encoders.
+    reverseEncoder({} as FixedSizeEncoder<string>) satisfies FixedSizeEncoder<string>;
+    // @ts-expect-error Expected a fixed size encoder.
+    reverseEncoder({} as VariableSizeEncoder<string>);
+    // @ts-expect-error Expected a fixed size encoder.
+    reverseEncoder({} as Encoder<string>);
+}
+
+{
+    // [reverseDecoder]: It only works with fixed size decoders.
+    reverseDecoder({} as FixedSizeDecoder<string>) satisfies FixedSizeDecoder<string>;
+    // @ts-expect-error Expected a fixed size decoder.
+    reverseDecoder({} as VariableSizeDecoder<string>);
+    // @ts-expect-error Expected a fixed size decoder.
+    reverseDecoder({} as Decoder<string>);
+}
+
+{
+    // [reverseCodec]: It only works with fixed size codecs.
+    reverseCodec({} as FixedSizeCodec<string>) satisfies FixedSizeCodec<string>;
+    // @ts-expect-error Expected a fixed size codec.
+    reverseCodec({} as VariableSizeCodec<string>);
+    // @ts-expect-error Expected a fixed size codec.
+    reverseCodec({} as Codec<string>);
+}