@yume-chan/struct 0.0.24 → 2.0.0

package/src/bipedal.ts

@@ -0,0 +1,65 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+import { isPromiseLike } from "@yume-chan/async";
+
+function advance<T>(
+    iterator: Iterator<unknown, T, unknown>,
+    next: unknown,
+): MaybePromiseLike<T> {
+    while (true) {
+        const { done, value } = iterator.next(next);
+        if (done) {
+            return value;
+        }
+        if (isPromiseLike(value)) {
+            return value.then(
+                (value) => advance(iterator, { resolved: value }),
+                (error: unknown) => advance(iterator, { error }),
+            );
+        }
+        next = value;
+    }
+}
+
+export type BipedalGenerator<This, T, A extends unknown[]> = (
+    this: This,
+    then: <U>(value: MaybePromiseLike<U>) => Iterable<unknown, U, unknown>,
+    ...args: A
+) => Generator<unknown, T, unknown>;
+
+/* #__NO_SIDE_EFFECTS__ */
+export function bipedal<This, T, A extends unknown[]>(
+    fn: BipedalGenerator<This, T, A>,
+    bindThis?: This,
+): { (this: This, ...args: A): MaybePromiseLike<T> } {
+    function result(this: This, ...args: A): MaybePromiseLike<T> {
+        const iterator = fn.call(
+            this,
+            function* <U>(
+                value: MaybePromiseLike<U>,
+            ): Generator<
+                PromiseLike<U>,
+                U,
+                { resolved: U } | { error: unknown }
+            > {
+                if (isPromiseLike(value)) {
+                    const result = yield value;
+                    if ("resolved" in result) {
+                        return result.resolved;
+                    } else {
+                        throw result.error;
+                    }
+                }
+
+                return value;
+            },
+            ...args,
+        ) as never;
+        return advance(iterator, undefined);
+    }
+
+    if (bindThis) {
+        return result.bind(bindThis);
+    } else {
+        return result;
+    }
+}

package/src/buffer.ts

@@ -0,0 +1,334 @@
+import type { Field } from "./field/index.js";
+import { field } from "./field/index.js";
+
+export const EmptyUint8Array = new Uint8Array(0);
+
+export interface Converter<From, To> {
+    convert: (value: From) => To;
+    back: (value: To) => From;
+}
+
+export interface BufferLengthConverter<K, KT> extends Converter<KT, number> {
+    field: K;
+}
+
+export interface BufferLike {
+    (length: number): Field<Uint8Array, never, never, Uint8Array>;
+    <U>(
+        length: number,
+        converter: Converter<Uint8Array, U>,
+    ): Field<U, never, never, Uint8Array>;
+
+    <K extends string>(
+        lengthField: K,
+    ): Field<Uint8Array, K, Record<K, number>, Uint8Array>;
+    <K extends string, U>(
+        lengthField: K,
+        converter: Converter<Uint8Array, U>,
+    ): Field<U, K, Record<K, number>, Uint8Array>;
+
+    <K extends string, KT>(
+        length: BufferLengthConverter<K, KT>,
+    ): Field<Uint8Array, K, Record<K, KT>, Uint8Array>;
+    <K extends string, KT, U>(
+        length: BufferLengthConverter<K, KT>,
+        converter: Converter<Uint8Array, U>,
+    ): Field<U, K, Record<K, KT>, Uint8Array>;
+
+    <LengthOmitInit extends string, LengthDependencies>(
+        length: Field<number, LengthOmitInit, LengthDependencies, number>,
+    ): Field<Uint8Array, LengthOmitInit, LengthDependencies, Uint8Array>;
+    <LengthOmitInit extends string, LengthDependencies, U>(
+        length: Field<number, LengthOmitInit, LengthDependencies, number>,
+        converter: Converter<Uint8Array, U>,
+    ): Field<U, LengthOmitInit, LengthDependencies, Uint8Array>;
+}
+
+function _buffer(length: number): Field<Uint8Array, never, never, Uint8Array>;
+function _buffer<U>(
+    length: number,
+    converter: Converter<Uint8Array, U>,
+): Field<U, never, never, Uint8Array>;
+
+function _buffer<K extends string>(
+    lengthField: K,
+): Field<Uint8Array, K, Record<K, number>, Uint8Array>;
+function _buffer<K extends string, U>(
+    lengthField: K,
+    converter: Converter<Uint8Array, U>,
+): Field<U, K, Record<K, number>, Uint8Array>;
+
+function _buffer<K extends string, KT>(
+    length: BufferLengthConverter<K, KT>,
+): Field<Uint8Array, K, Record<K, KT>, Uint8Array>;
+function _buffer<K extends string, KT, U>(
+    length: BufferLengthConverter<K, KT>,
+    converter: Converter<Uint8Array, U>,
+): Field<U, K, Record<K, KT>, Uint8Array>;
+
+function _buffer<LengthOmitInit extends string, LengthDependencies>(
+    length: Field<number, LengthOmitInit, LengthDependencies, number>,
+): Field<Uint8Array, LengthOmitInit, LengthDependencies, Uint8Array>;
+function _buffer<LengthOmitInit extends string, LengthDependencies, U>(
+    length: Field<number, LengthOmitInit, LengthDependencies, number>,
+    converter: Converter<Uint8Array, U>,
+): Field<U, LengthOmitInit, LengthDependencies, Uint8Array>;
+
+/* #__NO_SIDE_EFFECTS__ */
+function _buffer(
+    lengthOrField:
+        | string
+        | number
+        | Field<number, string, unknown, number>
+        | BufferLengthConverter<string, unknown>,
+    converter?: Converter<Uint8Array, unknown>,
+): Field<unknown, string, Record<string, unknown>, Uint8Array> {
+    // Fixed length
+    if (typeof lengthOrField === "number") {
+        if (converter) {
+            if (lengthOrField === 0) {
+                return field(
+                    0,
+                    "byob",
+                    () => {},
+                    // eslint-disable-next-line require-yield
+                    function* () {
+                        return converter.convert(EmptyUint8Array);
+                    },
+                );
+            }
+
+            return field(
+                0,
+                "byob",
+                (value, { buffer, index }) => {
+                    buffer.set(value.slice(0, lengthOrField), index);
+                },
+                function* (then, reader) {
+                    const array = yield* then(
+                        reader.readExactly(lengthOrField),
+                    );
+                    return converter.convert(array);
+                },
+                {
+                    init(value) {
+                        return converter.back(value);
+                    },
+                },
+            );
+        }
+
+        if (lengthOrField === 0) {
+            return field(
+                0,
+                "byob",
+                () => {},
+                // eslint-disable-next-line require-yield
+                function* () {
+                    return EmptyUint8Array;
+                },
+            );
+        }
+
+        return field(
+            0,
+            "byob",
+            (value, { buffer, index }) => {
+                buffer.set(value.slice(0, lengthOrField), index);
+            },
+            // eslint-disable-next-line require-yield
+            function* (_then, reader) {
+                return reader.readExactly(lengthOrField);
+            },
+        );
+    }
+
+    // Declare length field
+    // Some field types are `function`s
+    if (
+        (typeof lengthOrField === "object" ||
+            typeof lengthOrField === "function") &&
+        "serialize" in lengthOrField
+    ) {
+        if (converter) {
+            return field(
+                lengthOrField.size,
+                "default",
+                (value, { littleEndian }) => {
+                    if (lengthOrField.type === "default") {
+                        const lengthBuffer = lengthOrField.serialize(
+                            value.length,
+                            { littleEndian },
+                        );
+                        const result = new Uint8Array(
+                            lengthBuffer.length + value.length,
+                        );
+                        result.set(lengthBuffer, 0);
+                        result.set(value, lengthBuffer.length);
+                        return result;
+                    } else {
+                        const result = new Uint8Array(
+                            lengthOrField.size + value.length,
+                        );
+                        lengthOrField.serialize(value.length, {
+                            buffer: result,
+                            index: 0,
+                            littleEndian,
+                        });
+                        result.set(value, lengthOrField.size);
+                        return result;
+                    }
+                },
+                function* (then, reader, context) {
+                    const length = yield* then(
+                        lengthOrField.deserialize(reader, context),
+                    );
+                    const array = yield* then(reader.readExactly(length));
+                    return converter.convert(array);
+                },
+                {
+                    init(value) {
+                        return converter.back(value);
+                    },
+                },
+            );
+        }
+
+        return field(
+            lengthOrField.size,
+            "default",
+            (value, { littleEndian }) => {
+                if (lengthOrField.type === "default") {
+                    const lengthBuffer = lengthOrField.serialize(value.length, {
+                        littleEndian,
+                    });
+                    const result = new Uint8Array(
+                        lengthBuffer.length + value.length,
+                    );
+                    result.set(lengthBuffer, 0);
+                    result.set(value, lengthBuffer.length);
+                    return result;
+                } else {
+                    const result = new Uint8Array(
+                        lengthOrField.size + value.length,
+                    );
+                    lengthOrField.serialize(value.length, {
+                        buffer: result,
+                        index: 0,
+                        littleEndian,
+                    });
+                    result.set(value, lengthOrField.size);
+                    return result;
+                }
+            },
+            function* (then, reader, context) {
+                const length = yield* then(
+                    lengthOrField.deserialize(reader, context),
+                );
+                return yield* then(reader.readExactly(length));
+            },
+        );
+    }
+
+    // Reference exiting length field
+    if (typeof lengthOrField === "string") {
+        if (converter) {
+            return field(
+                0,
+                "default",
+                (source) => source,
+                // eslint-disable-next-line require-yield
+                function* (_then, reader, { dependencies }) {
+                    const length = dependencies[lengthOrField] as number;
+                    if (length === 0) {
+                        return EmptyUint8Array;
+                    }
+
+                    return reader.readExactly(length);
+                },
+                {
+                    init(value, dependencies) {
+                        const array = converter.back(value);
+                        dependencies[lengthOrField] = array.length;
+                        return array;
+                    },
+                },
+            );
+        }
+
+        return field(
+            0,
+            "default",
+            (source) => source,
+            // eslint-disable-next-line require-yield
+            function* (_then, reader, { dependencies }) {
+                const length = dependencies[lengthOrField] as number;
+                if (length === 0) {
+                    return EmptyUint8Array;
+                }
+
+                return reader.readExactly(length);
+            },
+            {
+                init(value, dependencies) {
+                    dependencies[lengthOrField] = (value as Uint8Array).length;
+                    return undefined;
+                },
+            },
+        );
+    }
+
+    // Reference existing length field + converter
+    if (converter) {
+        return field(
+            0,
+            "default",
+            (source) => source,
+            // eslint-disable-next-line require-yield
+            function* (_then, reader, { dependencies }) {
+                const rawLength = dependencies[lengthOrField.field];
+                const length = lengthOrField.convert(rawLength);
+                if (length === 0) {
+                    return EmptyUint8Array;
+                }
+
+                return reader.readExactly(length);
+            },
+            {
+                init(value, dependencies) {
+                    const array = converter.back(value);
+                    dependencies[lengthOrField.field] = lengthOrField.back(
+                        array.length,
+                    );
+                    return array;
+                },
+            },
+        );
+    }
+
+    return field(
+        0,
+        "default",
+        (source) => source,
+        // eslint-disable-next-line require-yield
+        function* (_then, reader, { dependencies }) {
+            const rawLength = dependencies[lengthOrField.field];
+            const length = lengthOrField.convert(rawLength);
+            if (length === 0) {
+                return EmptyUint8Array;
+            }
+
+            return reader.readExactly(length);
+        },
+        {
+            init(value, dependencies) {
+                dependencies[lengthOrField.field] = lengthOrField.back(
+                    (value as Uint8Array).length,
+                );
+                return undefined;
+            },
+        },
+    );
+}
+
+export const buffer = _buffer;

package/src/concat.ts

@@ -0,0 +1,78 @@
+import type { FieldsValue, Struct, StructFields } from "./struct.js";
+import { struct } from "./struct.js";
+
+type UnionToIntersection<U> = (
+    U extends unknown ? (x: U) => void : never
+) extends (x: infer I) => void
+    ? I
+    : never;
+
+type As<T, U> = T extends infer V extends U ? V : never;
+
+export type ConcatFields<
+    T extends Struct<
+        StructFields,
+        Record<PropertyKey, unknown> | undefined,
+        unknown
+    >[],
+> = As<UnionToIntersection<T[number]["fields"]>, StructFields>;
+
+type ConcatFieldValues<
+    T extends Struct<
+        StructFields,
+        Record<PropertyKey, unknown> | undefined,
+        unknown
+    >[],
+> = FieldsValue<ConcatFields<T>>;
+
+type ExtraToUnion<Extra extends Record<PropertyKey, unknown> | undefined> =
+    Extra extends undefined ? never : Extra;
+
+export type ConcatExtras<
+    T extends Struct<
+        StructFields,
+        Record<PropertyKey, unknown> | undefined,
+        unknown
+    >[],
+> = As<
+    UnionToIntersection<ExtraToUnion<T[number]["extra"]>>,
+    Record<PropertyKey, unknown>
+>;
+
+/* #__NO_SIDE_EFFECTS__ */
+export function concat<
+    T extends Struct<
+        StructFields,
+        Record<PropertyKey, unknown> | undefined,
+        unknown
+    >[],
+    PostDeserialize = ConcatFieldValues<T> & ConcatExtras<T>,
+>(
+    options: {
+        littleEndian: boolean;
+        postDeserialize?: (
+            this: ConcatFieldValues<T> & ConcatExtras<T>,
+            value: ConcatFieldValues<T> & ConcatExtras<T>,
+        ) => PostDeserialize;
+    },
+    ...structs: T
+): Struct<ConcatFields<T>, ConcatExtras<T>, PostDeserialize> {
+    return struct(
+        structs.reduce(
+            (fields, struct) => Object.assign(fields, struct.fields),
+            {},
+        ) as never,
+        {
+            littleEndian: options.littleEndian,
+            postDeserialize: options.postDeserialize,
+            extra: structs.reduce(
+                (extras, struct) =>
+                    Object.defineProperties(
+                        extras,
+                        Object.getOwnPropertyDescriptors(struct.extra),
+                    ),
+                {},
+            ) as never,
+        },
+    ) as never;
+}

package/src/extend.ts

@@ -0,0 +1,37 @@
+import type {
+    ExtraToIntersection,
+    FieldsValue,
+    Struct,
+    StructFields,
+} from "./struct.js";
+import { struct } from "./struct.js";
+
+/* #__NO_SIDE_EFFECTS__ */
+export function extend<
+    Base extends Struct<
+        StructFields,
+        Record<PropertyKey, unknown> | undefined,
+        unknown
+    >,
+    Fields extends StructFields,
+    PostDeserialize = FieldsValue<Base["fields"] & Fields> &
+        ExtraToIntersection<Base["extra"]>,
+>(
+    base: Base,
+    fields: Fields,
+    options?: {
+        littleEndian?: boolean | undefined;
+        postDeserialize?: (
+            this: FieldsValue<Base["fields"] & Fields> &
+                ExtraToIntersection<Base["extra"]>,
+            value: FieldsValue<Base["fields"] & Fields> &
+                ExtraToIntersection<Base["extra"]>,
+        ) => PostDeserialize;
+    },
+): Struct<Base["fields"] & Fields, Base["extra"], PostDeserialize> {
+    return struct(Object.assign({}, base.fields, fields), {
+        littleEndian: options?.littleEndian ?? base.littleEndian,
+        extra: base.extra as never,
+        postDeserialize: options?.postDeserialize,
+    }) as never;
+}

package/src/field/factory.ts

@@ -0,0 +1,64 @@
+import type { BipedalGenerator } from "../bipedal.js";
+import { bipedal } from "../bipedal.js";
+import type { AsyncExactReadable } from "../readable.js";
+
+import type {
+    ByobFieldSerializer,
+    DefaultFieldSerializer,
+} from "./serialize.js";
+import { byobFieldSerializer, defaultFieldSerializer } from "./serialize.js";
+import type { Field, FieldDeserializeContext, FieldOptions } from "./types.js";
+
+export type BipedalFieldDeserializer<T, D> = BipedalGenerator<
+    undefined,
+    T,
+    [reader: AsyncExactReadable, context: FieldDeserializeContext<D>]
+>;
+
+// eslint-disable-next-line @typescript-eslint/max-params
+function _field<T, OmitInit extends string, D, Raw = T>(
+    size: number,
+    type: "default",
+    serialize: DefaultFieldSerializer<Raw>,
+    deserialize: BipedalFieldDeserializer<T, D>,
+    options?: FieldOptions<T, OmitInit, D, Raw>,
+): Field<T, OmitInit, D, Raw>;
+// eslint-disable-next-line @typescript-eslint/max-params
+function _field<T, OmitInit extends string, D, Raw = T>(
+    size: number,
+    type: "byob",
+    serialize: ByobFieldSerializer<Raw>,
+    deserialize: BipedalFieldDeserializer<T, D>,
+    options?: FieldOptions<T, OmitInit, D, Raw>,
+): Field<T, OmitInit, D, Raw>;
+/* #__NO_SIDE_EFFECTS__ */
+// eslint-disable-next-line @typescript-eslint/max-params
+function _field<T, OmitInit extends string, D, Raw = T>(
+    size: number,
+    type: "default" | "byob",
+    serialize: DefaultFieldSerializer<Raw> | ByobFieldSerializer<Raw>,
+    deserialize: BipedalFieldDeserializer<T, D>,
+    options?: FieldOptions<T, OmitInit, D, Raw>,
+): Field<T, OmitInit, D, Raw> {
+    const field: Field<T, OmitInit, D, Raw> = {
+        size,
+        type: type,
+        serialize:
+            type === "default"
+                ? defaultFieldSerializer(
+                      serialize as DefaultFieldSerializer<Raw>,
+                  )
+                : byobFieldSerializer(
+                      size,
+                      serialize as ByobFieldSerializer<Raw>,
+                  ),
+        deserialize: bipedal(deserialize) as never,
+        omitInit: options?.omitInit,
+    };
+    if (options?.init) {
+        field.init = options.init;
+    }
+    return field;
+}
+
+export const field = _field;

package/src/field/index.ts

@@ -0,0 +1,3 @@
+export * from "./factory.js";
+export * from "./serialize.js";
+export * from "./types.js";

package/src/field/serialize.ts

@@ -0,0 +1,58 @@
+import type {
+    FieldByobSerializeContext,
+    FieldDefaultSerializeContext,
+    FieldSerializer,
+} from "./types.js";
+
+export type DefaultFieldSerializer<T> = (
+    source: T,
+    context: FieldDefaultSerializeContext,
+) => Uint8Array;
+
+/* Adapt default field serializer to universal field serializer */
+export function defaultFieldSerializer<T>(
+    serializer: DefaultFieldSerializer<T>,
+): FieldSerializer<T>["serialize"] {
+    return (
+        source,
+        context: FieldDefaultSerializeContext | FieldByobSerializeContext,
+    ): never => {
+        if ("buffer" in context) {
+            const buffer = serializer(source, context);
+            context.buffer.set(buffer, context.index);
+            return buffer.length as never;
+        } else {
+            return serializer(source, context) as never;
+        }
+    };
+}
+
+export type ByobFieldSerializer<T> = (
+    source: T,
+    context: FieldByobSerializeContext & { index: number },
+) => void;
+
+/* Adapt byob field serializer to universal field serializer */
+export function byobFieldSerializer<T>(
+    size: number,
+    serializer: ByobFieldSerializer<T>,
+): FieldSerializer<T>["serialize"] {
+    return (
+        source,
+        context: FieldDefaultSerializeContext | FieldByobSerializeContext,
+    ): never => {
+        if ("buffer" in context) {
+            context.index ??= 0;
+            serializer(source, context as never);
+            return size as never;
+        } else {
+            const buffer = new Uint8Array(size);
+            serializer(source, {
+                buffer,
+                index: 0,
+                littleEndian: context.littleEndian,
+            });
+            return buffer as never;
+        }
+    };
+}

package/src/field/types.ts

@@ -0,0 +1,48 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
+
+import type { AsyncExactReadable, ExactReadable } from "../readable.js";
+
+export interface FieldDefaultSerializeContext {
+    littleEndian: boolean;
+}
+
+export interface FieldByobSerializeContext
+    extends FieldDefaultSerializeContext {
+    buffer: Uint8Array;
+    index?: number;
+}
+
+export interface FieldSerializer<T> {
+    type: "default" | "byob";
+    size: number;
+
+    serialize(source: T, context: FieldDefaultSerializeContext): Uint8Array;
+    serialize(source: T, context: FieldByobSerializeContext): number;
+}
+
+export interface Field<T, OmitInit extends string, D, Raw = T>
+    extends FieldSerializer<Raw>,
+        FieldDeserializer<T, D> {
+    omitInit: OmitInit | undefined;
+
+    init?(value: T, dependencies: D): Raw | undefined;
+}
+
+export interface FieldDeserializeContext<D> {
+    littleEndian: boolean;
+    dependencies: D;
+}
+
+export interface FieldDeserializer<T, D> {
+    deserialize(reader: ExactReadable, context: FieldDeserializeContext<D>): T;
+    deserialize(
+        reader: AsyncExactReadable,
+        context: FieldDeserializeContext<D>,
+    ): MaybePromiseLike<T>;
+}
+
+export interface FieldOptions<T, OmitInit extends string, D, Raw = T> {
+    omitInit?: OmitInit;
+    dependencies?: D;
+    init?: (value: T, dependencies: D) => Raw | undefined;
+}