@yume-chan/struct 0.0.23 → 1.0.0

package/src/types/buffer/base.ts

@@ -1,197 +0,0 @@
-import type {
-    AsyncExactReadable,
-    ExactReadable,
-    StructOptions,
-    StructValue,
-} from "../../basic/index.js";
-import { StructFieldDefinition, StructFieldValue } from "../../basic/index.js";
-import { SyncPromise } from "../../sync-promise.js";
-import type { ValueOrPromise } from "../../utils.js";
-import { decodeUtf8, encodeUtf8 } from "../../utils.js";
-
-/**
- * Base class for all types that
- * can be converted from an `Uint8Array` when deserialized,
- * and need to be converted to an `Uint8Array` when serializing
- *
- * @template TValue The actual TypeScript type of this type
- * @template TTypeScriptType Optional another type (should be compatible with `TType`)
- * specified by user when creating field definitions.
- */
-export abstract class BufferFieldSubType<
-    TValue = unknown,
-    TTypeScriptType = TValue,
-> {
-    readonly TTypeScriptType!: TTypeScriptType;
-
-    /**
-     * When implemented in derived classes, converts the type-specific `value` to an `Uint8Array`
-     *
-     * This function should be "pure", i.e.,
-     * same `value` should always be converted to `Uint8Array`s that have same content.
-     */
-    abstract toBuffer(value: TValue): Uint8Array;
-
-    /** When implemented in derived classes, converts the `Uint8Array` to a type-specific value */
-    abstract toValue(array: Uint8Array): TValue;
-
-    /**
-     * When implemented in derived classes, gets the size in byte of the type-specific `value`.
-     *
-     * If the size can't be calculated without first converting the `value` back to an `Uint8Array`,
-     * implementer can returns `-1`, so the caller will get its size by first converting it to
-     * an `Uint8Array` (and cache the result).
-     */
-    abstract getSize(value: TValue): number;
-}
-
-/** An `BufferFieldSubType` that's actually an `Uint8Array` */
-export class Uint8ArrayBufferFieldSubType<
-    TTypeScriptType = Uint8Array,
-> extends BufferFieldSubType<Uint8Array, TTypeScriptType> {
-    static readonly Instance = new Uint8ArrayBufferFieldSubType();
-
-    protected constructor() {
-        super();
-    }
-
-    toBuffer(value: Uint8Array): Uint8Array {
-        return value;
-    }
-
-    toValue(buffer: Uint8Array): Uint8Array {
-        return buffer;
-    }
-
-    getSize(value: Uint8Array): number {
-        return value.byteLength;
-    }
-}
-
-/** An `BufferFieldSubType` that converts between `Uint8Array` and `string` */
-export class StringBufferFieldSubType<
-    TTypeScriptType = string,
-> extends BufferFieldSubType<string, TTypeScriptType> {
-    static readonly Instance = new StringBufferFieldSubType();
-
-    toBuffer(value: string): Uint8Array {
-        return encodeUtf8(value);
-    }
-
-    toValue(array: Uint8Array): string {
-        return decodeUtf8(array);
-    }
-
-    getSize(): number {
-        // Return `-1`, so `BufferLikeFieldDefinition` will
-        // convert this `value` into an `Uint8Array` (and cache the result),
-        // Then get the size from that `Uint8Array`
-        return -1;
-    }
-}
-
-export const EMPTY_UINT8_ARRAY = new Uint8Array(0);
-
-export abstract class BufferLikeFieldDefinition<
-    TType extends BufferFieldSubType<any, any> = BufferFieldSubType<
-        unknown,
-        unknown
-    >,
-    TOptions = void,
-    TOmitInitKey extends PropertyKey = never,
-    TTypeScriptType = TType["TTypeScriptType"],
-> extends StructFieldDefinition<TOptions, TTypeScriptType, TOmitInitKey> {
-    readonly type: TType;
-
-    constructor(type: TType, options: TOptions) {
-        super(options);
-        this.type = type;
-    }
-
-    protected getDeserializeSize(struct: StructValue): number {
-        void struct;
-        return this.getSize();
-    }
-
-    /**
-     * When implemented in derived classes, creates a `StructFieldValue` for the current field definition.
-     */
-    create(
-        options: Readonly<StructOptions>,
-        struct: StructValue,
-        value: TType["TTypeScriptType"],
-        array?: Uint8Array,
-    ): BufferLikeFieldValue<this> {
-        return new BufferLikeFieldValue(this, options, struct, value, array);
-    }
-
-    override deserialize(
-        options: Readonly<StructOptions>,
-        stream: ExactReadable,
-        struct: StructValue,
-    ): BufferLikeFieldValue<this>;
-    override deserialize(
-        options: Readonly<StructOptions>,
-        stream: AsyncExactReadable,
-        struct: StructValue,
-    ): Promise<BufferLikeFieldValue<this>>;
-    override deserialize(
-        options: Readonly<StructOptions>,
-        stream: ExactReadable | AsyncExactReadable,
-        struct: StructValue,
-    ): ValueOrPromise<BufferLikeFieldValue<this>> {
-        return SyncPromise.try(() => {
-            const size = this.getDeserializeSize(struct);
-            if (size === 0) {
-                return EMPTY_UINT8_ARRAY;
-            } else {
-                return stream.readExactly(size);
-            }
-        })
-            .then((array) => {
-                const value = this.type.toValue(array);
-                return this.create(options, struct, value, array);
-            })
-            .valueOrPromise();
-    }
-}
-
-export class BufferLikeFieldValue<
-    TDefinition extends BufferLikeFieldDefinition<
-        BufferFieldSubType<unknown, unknown>,
-        any,
-        any
-    >,
-> extends StructFieldValue<TDefinition> {
-    protected array: Uint8Array | undefined;
-
-    constructor(
-        definition: TDefinition,
-        options: Readonly<StructOptions>,
-        struct: StructValue,
-        value: TDefinition["TValue"],
-        array?: Uint8Array,
-    ) {
-        super(definition, options, struct, value);
-        this.array = array;
-    }
-
-    override set(value: TDefinition["TValue"]): void {
-        super.set(value);
-        // When value changes, clear the cached `array`
-        // It will be lazily calculated in `serialize()`
-        this.array = undefined;
-    }
-
-    serialize(dataView: DataView, offset: number): void {
-        if (!this.array) {
-            this.array = this.definition.type.toBuffer(this.value);
-        }
-
-        new Uint8Array(
-            dataView.buffer,
-            dataView.byteOffset,
-            dataView.byteLength,
-        ).set(this.array, offset);
-    }
-}

package/src/types/buffer/fixed-length.ts

@@ -1,17 +0,0 @@
-import type { BufferFieldSubType } from "./base.js";
-import { BufferLikeFieldDefinition } from "./base.js";
-
-export interface FixedLengthBufferLikeFieldOptions {
-    length: number;
-}
-
-export class FixedLengthBufferLikeFieldDefinition<
-    TType extends BufferFieldSubType = BufferFieldSubType,
-    TOptions extends
-        FixedLengthBufferLikeFieldOptions = FixedLengthBufferLikeFieldOptions,
-    TTypeScriptType = TType["TTypeScriptType"],
-> extends BufferLikeFieldDefinition<TType, TOptions, never, TTypeScriptType> {
-    getSize(): number {
-        return this.options.length;
-    }
-}

package/src/types/buffer/index.ts

@@ -1,3 +0,0 @@
-export * from "./base.js";
-export * from "./fixed-length.js";
-export * from "./variable-length.js";

package/src/types/buffer/variable-length.ts

@@ -1,174 +0,0 @@
-import type {
-    StructFieldDefinition,
-    StructOptions,
-    StructValue,
-} from "../../basic/index.js";
-import { StructFieldValue } from "../../basic/index.js";
-import type { KeysOfType } from "../../utils.js";
-
-import type { BufferFieldSubType } from "./base.js";
-import { BufferLikeFieldDefinition, BufferLikeFieldValue } from "./base.js";
-
-export type LengthField<TFields> = KeysOfType<TFields, number | string>;
-
-export interface VariableLengthBufferLikeFieldOptions<
-    TFields = object,
-    TLengthField extends LengthField<TFields> = any,
-> {
-    /**
-     * The name of the field that contains the length of the buffer.
-     *
-     * This field must be a `number` or `string` (can't be `bigint`) field.
-     */
-    lengthField: TLengthField;
-
-    /**
-     * If the `lengthField` refers to a string field,
-     * what radix to use when converting the string to a number.
-     *
-     * @default 10
-     */
-    lengthFieldRadix?: number;
-}
-
-export class VariableLengthBufferLikeFieldDefinition<
-    TType extends BufferFieldSubType = BufferFieldSubType,
-    TOptions extends
-        VariableLengthBufferLikeFieldOptions = VariableLengthBufferLikeFieldOptions,
-    TTypeScriptType = TType["TTypeScriptType"],
-> extends BufferLikeFieldDefinition<
-    TType,
-    TOptions,
-    TOptions["lengthField"],
-    TTypeScriptType
-> {
-    getSize(): number {
-        return 0;
-    }
-
-    protected override getDeserializeSize(struct: StructValue) {
-        let value = struct.value[this.options.lengthField] as number | string;
-        if (typeof value === "string") {
-            value = Number.parseInt(value, this.options.lengthFieldRadix ?? 10);
-        }
-        return value;
-    }
-
-    override create(
-        options: Readonly<StructOptions>,
-        struct: StructValue,
-        value: TTypeScriptType,
-        array?: Uint8Array,
-    ): VariableLengthBufferLikeStructFieldValue<this> {
-        return new VariableLengthBufferLikeStructFieldValue(
-            this,
-            options,
-            struct,
-            value,
-            array,
-        );
-    }
-}
-
-export class VariableLengthBufferLikeStructFieldValue<
-    TDefinition extends
-        VariableLengthBufferLikeFieldDefinition = VariableLengthBufferLikeFieldDefinition,
-> extends BufferLikeFieldValue<TDefinition> {
-    protected length: number | undefined;
-
-    protected lengthFieldValue: VariableLengthBufferLikeFieldLengthValue;
-
-    constructor(
-        definition: TDefinition,
-        options: Readonly<StructOptions>,
-        struct: StructValue,
-        value: TDefinition["TValue"],
-        array?: Uint8Array,
-    ) {
-        super(definition, options, struct, value, array);
-
-        if (array) {
-            this.length = array.byteLength;
-        }
-
-        // Patch the associated length field.
-        const lengthField = this.definition.options.lengthField;
-
-        const originalValue = struct.get(lengthField);
-        this.lengthFieldValue = new VariableLengthBufferLikeFieldLengthValue(
-            originalValue,
-            this,
-        );
-        struct.set(lengthField, this.lengthFieldValue);
-    }
-
-    override getSize() {
-        if (this.length === undefined) {
-            this.length = this.definition.type.getSize(this.value);
-            if (this.length === -1) {
-                this.array = this.definition.type.toBuffer(this.value);
-                this.length = this.array.byteLength;
-            }
-        }
-
-        return this.length;
-    }
-
-    override set(value: unknown) {
-        super.set(value);
-        this.array = undefined;
-        this.length = undefined;
-    }
-}
-
-// Not using `VariableLengthBufferLikeStructFieldValue` directly makes writing tests much easier...
-type VariableLengthBufferLikeFieldValueLike = StructFieldValue<
-    StructFieldDefinition<VariableLengthBufferLikeFieldOptions, any, any>
->;
-
-export class VariableLengthBufferLikeFieldLengthValue extends StructFieldValue {
-    protected originalField: StructFieldValue;
-
-    protected bufferField: VariableLengthBufferLikeFieldValueLike;
-
-    constructor(
-        originalField: StructFieldValue,
-        arrayBufferField: VariableLengthBufferLikeFieldValueLike,
-    ) {
-        super(
-            originalField.definition,
-            originalField.options,
-            originalField.struct,
-            0,
-        );
-        this.originalField = originalField;
-        this.bufferField = arrayBufferField;
-    }
-
-    override getSize() {
-        return this.originalField.getSize();
-    }
-
-    override get() {
-        let value: string | number = this.bufferField.getSize();
-
-        const originalValue = this.originalField.get();
-        if (typeof originalValue === "string") {
-            value = value.toString(
-                this.bufferField.definition.options.lengthFieldRadix ?? 10,
-            );
-        }
-
-        return value;
-    }
-
-    override set() {
-        // Ignore setting
-        // It will always be in sync with the buffer size
-    }
-
-    serialize(dataView: DataView, offset: number) {
-        this.originalField.set(this.get());
-        this.originalField.serialize(dataView, offset);
-    }
-}

package/src/types/index.ts

@@ -1,3 +0,0 @@
-export * from "./bigint.js";
-export * from "./buffer/index.js";
-export * from "./number.js";

package/src/types/number.ts

@@ -1,173 +0,0 @@
-import type {
-    AsyncExactReadable,
-    ExactReadable,
-    StructOptions,
-    StructValue,
-} from "../basic/index.js";
-import { StructFieldDefinition, StructFieldValue } from "../basic/index.js";
-import { SyncPromise } from "../sync-promise.js";
-import type { ValueOrPromise } from "../utils.js";
-
-export interface NumberFieldType {
-    signed: boolean;
-    size: number;
-    deserialize(array: Uint8Array, littleEndian: boolean): number;
-    serialize(
-        dataView: DataView,
-        offset: number,
-        value: number,
-        littleEndian: boolean,
-    ): void;
-}
-
-export namespace NumberFieldType {
-    export const Uint8: NumberFieldType = {
-        signed: false,
-        size: 1,
-        deserialize(array) {
-            return array[0]!;
-        },
-        serialize(dataView, offset, value) {
-            dataView.setUint8(offset, value);
-        },
-    };
-
-    export const Int8: NumberFieldType = {
-        signed: true,
-        size: 1,
-        deserialize(array) {
-            const value = Uint8.deserialize(array, false);
-            return (value << 24) >> 24;
-        },
-        serialize(dataView, offset, value) {
-            dataView.setInt8(offset, value);
-        },
-    };
-
-    export const Uint16: NumberFieldType = {
-        signed: false,
-        size: 2,
-        deserialize(array, littleEndian) {
-            // PERF: Creating many `DataView`s over small buffers is 90% slower
-            // than this. Even if the `DataView` is cached, `DataView#getUint16`
-            // is still 1% slower than this.
-            const a = (array[1]! << 8) | array[0]!;
-            const b = (array[0]! << 8) | array[1]!;
-            return littleEndian ? a : b;
-        },
-        serialize(dataView, offset, value, littleEndian) {
-            dataView.setUint16(offset, value, littleEndian);
-        },
-    };
-
-    export const Int16: NumberFieldType = {
-        signed: true,
-        size: 2,
-        deserialize(array, littleEndian) {
-            const value = Uint16.deserialize(array, littleEndian);
-            return (value << 16) >> 16;
-        },
-        serialize(dataView, offset, value, littleEndian) {
-            dataView.setInt16(offset, value, littleEndian);
-        },
-    };
-
-    export const Uint32: NumberFieldType = {
-        signed: false,
-        size: 4,
-        deserialize(array, littleEndian) {
-            const value = Int32.deserialize(array, littleEndian);
-            return value >>> 0;
-        },
-        serialize(dataView, offset, value, littleEndian) {
-            dataView.setUint32(offset, value, littleEndian);
-        },
-    };
-
-    export const Int32: NumberFieldType = {
-        signed: true,
-        size: 4,
-        deserialize(array, littleEndian) {
-            const a =
-                (array[3]! << 24) |
-                (array[2]! << 16) |
-                (array[1]! << 8) |
-                array[0]!;
-            const b =
-                (array[0]! << 24) |
-                (array[1]! << 16) |
-                (array[2]! << 8) |
-                array[3]!;
-            return littleEndian ? a : b;
-        },
-        serialize(dataView, offset, value, littleEndian) {
-            dataView.setInt32(offset, value, littleEndian);
-        },
-    };
-}
-
-export class NumberFieldDefinition<
-    TType extends NumberFieldType = NumberFieldType,
-    TTypeScriptType = number,
-> extends StructFieldDefinition<void, TTypeScriptType> {
-    readonly type: TType;
-
-    constructor(type: TType, typescriptType?: TTypeScriptType) {
-        void typescriptType;
-        super();
-        this.type = type;
-    }
-
-    getSize(): number {
-        return this.type.size;
-    }
-
-    create(
-        options: Readonly<StructOptions>,
-        struct: StructValue,
-        value: TTypeScriptType,
-    ): NumberFieldValue<this> {
-        return new NumberFieldValue(this, options, struct, value);
-    }
-
-    override deserialize(
-        options: Readonly<StructOptions>,
-        stream: ExactReadable,
-        struct: StructValue,
-    ): NumberFieldValue<this>;
-    override deserialize(
-        options: Readonly<StructOptions>,
-        stream: AsyncExactReadable,
-        struct: StructValue,
-    ): Promise<NumberFieldValue<this>>;
-    override deserialize(
-        options: Readonly<StructOptions>,
-        stream: ExactReadable | AsyncExactReadable,
-        struct: StructValue,
-    ): ValueOrPromise<NumberFieldValue<this>> {
-        return SyncPromise.try(() => {
-            return stream.readExactly(this.getSize());
-        })
-            .then((array) => {
-                const value = this.type.deserialize(
-                    array,
-                    options.littleEndian,
-                );
-                return this.create(options, struct, value as any);
-            })
-            .valueOrPromise();
-    }
-}
-
-export class NumberFieldValue<
-    TDefinition extends NumberFieldDefinition<NumberFieldType, any>,
-> extends StructFieldValue<TDefinition> {
-    serialize(dataView: DataView, offset: number): void {
-        this.definition.type.serialize(
-            dataView,
-            offset,
-            this.value,
-            this.options.littleEndian,
-        );
-    }
-}