@yume-chan/struct 0.0.22 → 0.0.24

package/src/types/buffer/base.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 import type {
     AsyncExactReadable,
     ExactReadable,
@@ -10,46 +11,49 @@ 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
+ * A converter for buffer-like fields.
+ * It converts `Uint8Array`s to custom-typed values when deserializing,
+ * and convert values back to `Uint8Array`s 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.
+ * @template TValue The type of the value that the converter converts to/from `Uint8Array`.
+ * @template TTypeScriptType Optionally another type to refine `TValue`.
+ * For example, `TValue` is `string`, and `TTypeScriptType` is `"foo" | "bar"`.
+ * `TValue` is specified by the developer when creating an converter implementation,
+ * `TTypeScriptType` is specified by the user when creating a field.
  */
-export abstract class BufferFieldSubType<
+export abstract class BufferFieldConverter<
     TValue = unknown,
     TTypeScriptType = TValue,
 > {
     readonly TTypeScriptType!: TTypeScriptType;
 
     /**
-     * When implemented in derived classes, converts the type-specific `value` to an `Uint8Array`
+     * When implemented in derived classes, converts the custom `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 */
+    /** When implemented in derived classes, converts the `Uint8Array` to a custom value */
     abstract toValue(array: Uint8Array): TValue;
 
     /**
-     * When implemented in derived classes, gets the size in byte of the type-specific `value`.
+     * When implemented in derived classes, gets the size in byte of the custom `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).
+     * If the size can't be determined without first converting the `value` back to an `Uint8Array`,
+     * the implementer should return `undefined`. In which case, the caller will call `toBuffer` to
+     * convert the value to a `Uint8Array`, then read the length of the `Uint8Array`. The caller can
+     * cache the result so the serialization process doesn't need to call `toBuffer` again.
      */
-    abstract getSize(value: TValue): number;
+    abstract getSize(value: TValue): number | undefined;
 }
 
-/** An `BufferFieldSubType` that's actually an `Uint8Array` */
-export class Uint8ArrayBufferFieldSubType<
+/** An identity converter, doesn't convert to anything else. */
+export class Uint8ArrayBufferFieldConverter<
     TTypeScriptType = Uint8Array,
-> extends BufferFieldSubType<Uint8Array, TTypeScriptType> {
-    static readonly Instance = new Uint8ArrayBufferFieldSubType();
+> extends BufferFieldConverter<Uint8Array, TTypeScriptType> {
+    static readonly Instance = new Uint8ArrayBufferFieldConverter();
 
     protected constructor() {
         super();
@@ -64,15 +68,15 @@ export class Uint8ArrayBufferFieldSubType<
     }
 
     getSize(value: Uint8Array): number {
-        return value.byteLength;
+        return value.length;
     }
 }
 
 /** An `BufferFieldSubType` that converts between `Uint8Array` and `string` */
-export class StringBufferFieldSubType<
+export class StringBufferFieldConverter<
     TTypeScriptType = string,
-> extends BufferFieldSubType<string, TTypeScriptType> {
-    static readonly Instance = new StringBufferFieldSubType();
+> extends BufferFieldConverter<string, TTypeScriptType> {
+    static readonly Instance = new StringBufferFieldConverter();
 
     toBuffer(value: string): Uint8Array {
         return encodeUtf8(value);
@@ -82,30 +86,29 @@ export class StringBufferFieldSubType<
         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;
+    getSize(): number | undefined {
+        // See the note in `BufferFieldConverter.getSize`
+        return undefined;
     }
 }
 
 export const EMPTY_UINT8_ARRAY = new Uint8Array(0);
 
 export abstract class BufferLikeFieldDefinition<
-    TType extends BufferFieldSubType<any, any> = BufferFieldSubType<
+    TConverter extends BufferFieldConverter<
         unknown,
         unknown
-    >,
+    > = BufferFieldConverter<unknown, unknown>,
     TOptions = void,
     TOmitInitKey extends PropertyKey = never,
-    TTypeScriptType = TType["TTypeScriptType"],
+    TTypeScriptType = TConverter["TTypeScriptType"],
 > extends StructFieldDefinition<TOptions, TTypeScriptType, TOmitInitKey> {
-    readonly type: TType;
+    readonly converter: TConverter;
+    readonly TTypeScriptType!: TTypeScriptType;
 
-    constructor(type: TType, options: TOptions) {
+    constructor(converter: TConverter, options: TOptions) {
         super(options);
-        this.type = type;
+        this.converter = converter;
     }
 
     protected getDeserializeSize(struct: StructValue): number {
@@ -119,7 +122,7 @@ export abstract class BufferLikeFieldDefinition<
     create(
         options: Readonly<StructOptions>,
         struct: StructValue,
-        value: TType["TTypeScriptType"],
+        value: TTypeScriptType,
         array?: Uint8Array,
     ): BufferLikeFieldValue<this> {
         return new BufferLikeFieldValue(this, options, struct, value, array);
@@ -149,7 +152,7 @@ export abstract class BufferLikeFieldDefinition<
             }
         })
             .then((array) => {
-                const value = this.type.toValue(array);
+                const value = this.converter.toValue(array) as TTypeScriptType;
                 return this.create(options, struct, value, array);
             })
             .valueOrPromise();
@@ -158,7 +161,8 @@ export abstract class BufferLikeFieldDefinition<
 
 export class BufferLikeFieldValue<
     TDefinition extends BufferLikeFieldDefinition<
-        BufferFieldSubType<unknown, unknown>,
+        BufferFieldConverter<unknown, unknown>,
+        any,
         any,
         any
     >,
@@ -169,7 +173,7 @@ export class BufferLikeFieldValue<
         definition: TDefinition,
         options: Readonly<StructOptions>,
         struct: StructValue,
-        value: TDefinition["TValue"],
+        value: TDefinition["TTypeScriptType"],
         array?: Uint8Array,
     ) {
         super(definition, options, struct, value);
@@ -183,15 +187,12 @@ export class BufferLikeFieldValue<
         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);
+    override serialize(
+        dataView: DataView,
+        array: Uint8Array,
+        offset: number,
+    ): void {
+        this.array ??= this.definition.converter.toBuffer(this.value);
+        array.set(this.array, offset);
     }
 }

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

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

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

@@ -1,3 +1,6 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
 import type {
     StructFieldDefinition,
     StructOptions,
@@ -6,13 +9,13 @@ import type {
 import { StructFieldValue } from "../../basic/index.js";
 import type { KeysOfType } from "../../utils.js";
 
-import type { BufferFieldSubType } from "./base.js";
+import type { BufferFieldConverter } from "./base.js";
 import { BufferLikeFieldDefinition, BufferLikeFieldValue } from "./base.js";
 
 export type LengthField<TFields> = KeysOfType<TFields, number | string>;
 
 export interface VariableLengthBufferLikeFieldOptions<
-    TFields = object,
+    TFields extends object = object,
     TLengthField extends LengthField<TFields> = any,
 > {
     /**
@@ -32,12 +35,12 @@ export interface VariableLengthBufferLikeFieldOptions<
 }
 
 export class VariableLengthBufferLikeFieldDefinition<
-    TType extends BufferFieldSubType = BufferFieldSubType,
+    TConverter extends BufferFieldConverter = BufferFieldConverter,
     TOptions extends
         VariableLengthBufferLikeFieldOptions = VariableLengthBufferLikeFieldOptions,
-    TTypeScriptType = TType["TTypeScriptType"],
+    TTypeScriptType = TConverter["TTypeScriptType"],
 > extends BufferLikeFieldDefinition<
-    TType,
+    TConverter,
     TOptions,
     TOptions["lengthField"],
     TTypeScriptType
@@ -88,11 +91,11 @@ export class VariableLengthBufferLikeStructFieldValue<
         super(definition, options, struct, value, array);
 
         if (array) {
-            this.length = array.byteLength;
+            this.length = array.length;
         }
 
         // Patch the associated length field.
-        const lengthField = this.definition.options.lengthField;
+        const lengthField = this.definition.options.lengthField as PropertyKey;
 
         const originalValue = struct.get(lengthField);
         this.lengthFieldValue = new VariableLengthBufferLikeFieldLengthValue(
@@ -102,13 +105,24 @@ export class VariableLengthBufferLikeStructFieldValue<
         struct.set(lengthField, this.lengthFieldValue);
     }
 
-    override getSize() {
+    #tryGetSize() {
+        const length = this.definition.converter.getSize(this.value);
+        if (length !== undefined && length < 0) {
+            throw new Error("Invalid length");
+        }
+        return length;
+    }
+
+    override getSize(): number {
         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;
-            }
+            // first try to get the size from the converter
+            this.length = this.#tryGetSize();
+        }
+
+        if (this.length === undefined) {
+            // The converter doesn't know the size, so convert the value to a buffer to get its size
+            this.array = this.definition.converter.toBuffer(this.value);
+            this.length = this.array.length;
         }
 
         return this.length;
@@ -123,39 +137,49 @@ export class VariableLengthBufferLikeStructFieldValue<
 
 // Not using `VariableLengthBufferLikeStructFieldValue` directly makes writing tests much easier...
 type VariableLengthBufferLikeFieldValueLike = StructFieldValue<
-    StructFieldDefinition<VariableLengthBufferLikeFieldOptions, any, any>
+    StructFieldDefinition<
+        VariableLengthBufferLikeFieldOptions<any, any>,
+        any,
+        any
+    >
 >;
 
-export class VariableLengthBufferLikeFieldLengthValue extends StructFieldValue {
-    protected originalField: StructFieldValue;
+export class VariableLengthBufferLikeFieldLengthValue extends StructFieldValue<
+    StructFieldDefinition<unknown, unknown, PropertyKey>
+> {
+    protected originalValue: StructFieldValue<
+        StructFieldDefinition<unknown, unknown, PropertyKey>
+    >;
 
-    protected bufferField: VariableLengthBufferLikeFieldValueLike;
+    protected bufferValue: VariableLengthBufferLikeFieldValueLike;
 
     constructor(
-        originalField: StructFieldValue,
-        arrayBufferField: VariableLengthBufferLikeFieldValueLike,
+        originalValue: StructFieldValue<
+            StructFieldDefinition<unknown, unknown, PropertyKey>
+        >,
+        bufferValue: VariableLengthBufferLikeFieldValueLike,
     ) {
         super(
-            originalField.definition,
-            originalField.options,
-            originalField.struct,
+            originalValue.definition,
+            originalValue.options,
+            originalValue.struct,
             0,
         );
-        this.originalField = originalField;
-        this.bufferField = arrayBufferField;
+        this.originalValue = originalValue;
+        this.bufferValue = bufferValue;
     }
 
     override getSize() {
-        return this.originalField.getSize();
+        return this.originalValue.getSize();
     }
 
     override get() {
-        let value: string | number = this.bufferField.getSize();
+        let value: string | number = this.bufferValue.getSize();
 
-        const originalValue = this.originalField.get();
+        const originalValue = this.originalValue.get();
         if (typeof originalValue === "string") {
             value = value.toString(
-                this.bufferField.definition.options.lengthFieldRadix ?? 10,
+                this.bufferValue.definition.options.lengthFieldRadix ?? 10,
             );
         }
 
@@ -167,8 +191,8 @@ export class VariableLengthBufferLikeFieldLengthValue extends StructFieldValue {
         // 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);
+    serialize(dataView: DataView, array: Uint8Array, offset: number) {
+        this.originalValue.set(this.get());
+        this.originalValue.serialize(dataView, array, offset);
     }
 }

package/src/types/number.ts

@@ -1,3 +1,11 @@
+import {
+    getInt16,
+    getInt32,
+    getInt8,
+    getUint16,
+    getUint32,
+} from "@yume-chan/no-data-view";
+
 import type {
     AsyncExactReadable,
     ExactReadable,
@@ -8,7 +16,7 @@ import { StructFieldDefinition, StructFieldValue } from "../basic/index.js";
 import { SyncPromise } from "../sync-promise.js";
 import type { ValueOrPromise } from "../utils.js";
 
-export interface NumberFieldType {
+export interface NumberFieldVariant {
     signed: boolean;
     size: number;
     deserialize(array: Uint8Array, littleEndian: boolean): number;
@@ -20,8 +28,8 @@ export interface NumberFieldType {
     ): void;
 }
 
-export namespace NumberFieldType {
-    export const Uint8: NumberFieldType = {
+export namespace NumberFieldVariant {
+    export const Uint8: NumberFieldVariant = {
         signed: false,
         size: 1,
         deserialize(array) {
@@ -32,73 +40,58 @@ export namespace NumberFieldType {
         },
     };
 
-    export const Int8: NumberFieldType = {
+    export const Int8: NumberFieldVariant = {
         signed: true,
         size: 1,
         deserialize(array) {
-            const value = Uint8.deserialize(array, false);
-            return (value << 24) >> 24;
+            return getInt8(array, 0);
         },
         serialize(dataView, offset, value) {
             dataView.setInt8(offset, value);
         },
     };
 
-    export const Uint16: NumberFieldType = {
+    export const Uint16: NumberFieldVariant = {
         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;
+            return getUint16(array, 0, littleEndian);
         },
         serialize(dataView, offset, value, littleEndian) {
             dataView.setUint16(offset, value, littleEndian);
         },
     };
 
-    export const Int16: NumberFieldType = {
+    export const Int16: NumberFieldVariant = {
         signed: true,
         size: 2,
         deserialize(array, littleEndian) {
-            const value = Uint16.deserialize(array, littleEndian);
-            return (value << 16) >> 16;
+            return getInt16(array, 0, littleEndian);
         },
         serialize(dataView, offset, value, littleEndian) {
             dataView.setInt16(offset, value, littleEndian);
         },
     };
 
-    export const Uint32: NumberFieldType = {
+    export const Uint32: NumberFieldVariant = {
         signed: false,
         size: 4,
         deserialize(array, littleEndian) {
-            const value = Int32.deserialize(array, littleEndian);
-            return value >>> 0;
+            return getUint32(array, 0, littleEndian);
         },
         serialize(dataView, offset, value, littleEndian) {
             dataView.setUint32(offset, value, littleEndian);
         },
     };
 
-    export const Int32: NumberFieldType = {
+    export const Int32: NumberFieldVariant = {
         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;
+            return getInt32(array, 0, littleEndian);
         },
         serialize(dataView, offset, value, littleEndian) {
             dataView.setInt32(offset, value, littleEndian);
@@ -107,19 +100,19 @@ export namespace NumberFieldType {
 }
 
 export class NumberFieldDefinition<
-    TType extends NumberFieldType = NumberFieldType,
+    TVariant extends NumberFieldVariant = NumberFieldVariant,
     TTypeScriptType = number,
 > extends StructFieldDefinition<void, TTypeScriptType> {
-    readonly type: TType;
+    readonly variant: TVariant;
 
-    constructor(type: TType, typescriptType?: TTypeScriptType) {
+    constructor(variant: TVariant, typescriptType?: TTypeScriptType) {
         void typescriptType;
         super();
-        this.type = type;
+        this.variant = variant;
     }
 
     getSize(): number {
-        return this.type.size;
+        return this.variant.size;
     }
 
     create(
@@ -149,24 +142,24 @@ export class NumberFieldDefinition<
             return stream.readExactly(this.getSize());
         })
             .then((array) => {
-                const value = this.type.deserialize(
+                const value = this.variant.deserialize(
                     array,
                     options.littleEndian,
                 );
-                return this.create(options, struct, value as any);
+                return this.create(options, struct, value as never);
             })
             .valueOrPromise();
     }
 }
 
 export class NumberFieldValue<
-    TDefinition extends NumberFieldDefinition<NumberFieldType, any>,
+    TDefinition extends NumberFieldDefinition<NumberFieldVariant, unknown>,
 > extends StructFieldValue<TDefinition> {
-    serialize(dataView: DataView, offset: number): void {
-        this.definition.type.serialize(
+    serialize(dataView: DataView, array: Uint8Array, offset: number): void {
+        this.definition.variant.serialize(
             dataView,
             offset,
-            this.value,
+            this.value as never,
             this.options.littleEndian,
         );
     }

package/src/utils.ts

@@ -80,13 +80,15 @@ interface GlobalExtension {
 
 const { TextEncoder, TextDecoder } = globalThis as unknown as GlobalExtension;
 
-const Utf8Encoder = new TextEncoder();
-const Utf8Decoder = new TextDecoder();
+const SharedEncoder = new TextEncoder();
+const SharedDecoder = new TextDecoder();
 
 export function encodeUtf8(input: string): Uint8Array {
-    return Utf8Encoder.encode(input);
+    return SharedEncoder.encode(input);
 }
 
 export function decodeUtf8(buffer: ArrayBufferView | ArrayBuffer): string {
-    return Utf8Decoder.decode(buffer);
+    // `TextDecoder` has internal states in stream mode,
+    // but this method is not for stream mode, so the instance can be reused
+    return SharedDecoder.decode(buffer);
 }